Troubleshooting

Common operational challenges, error messages, and verified resolutions when working with the Akeneo Connector for Magento 2.

The connector could not authenticate with Akeneo PIM's OAuth endpoint or received an HTTP 401/403 status.

Verify that Enable Akeneo Connector is set to Yes in Stores → Configuration → Webkul → Akeneo Connector → General Settings.
Verify the Akeneo Portal URL in Stores → Configuration → Webkul → Akeneo Connector includes https:// with no trailing slash.
Confirm the Client ID and Secret match the credentials displayed under Connect → Connection Settings in Akeneo PIM.

Test connectivity directly from your Magento server terminal:

curl -I https://akeneo.yourstore.com/api/rest/v1/categories

If self-signed SSL certificates are used on development servers, add your internal root CA certificate to the system trust store.

2. Server Timeouts During Chunk Export

Exporting large batches of configurable products with numerous variants can exceed PHP or web server execution limits.

The UI progress bar halts with: "A technical problem with the server created an error".

Optimized Chunk Size: Configurable models export in optimized batches of 10 (LIMIT = 10) to ensure fast, reliable processing without memory spikes.

Increase Web Server Timeouts: In Nginx:

fastcgi_read_timeout 300;
proxy_read_timeout 300;

In Apache:

Timeout 300
ProxyTimeout 300

Increase PHP Execution Time: In php.ini:

max_execution_time = 300
memory_limit = 2G

Akeneo rejected an entity payload because a mandatory field, variant axis, or category relationship was missing or invalid.

Missing Super Attributes: When exporting product models, configurable attributes (such as color and size) must be mapped in Export Configuration → Attributes Mapping.
Family Variant Axes: The mapped super attributes must match the variant axes defined on the corresponding Akeneo Family Variant.
Empty Category Arrays: Ensure categories are assigned to products before exporting.

A Magento product contains an attribute option value that does not yet exist as an option code in Akeneo PIM.

Run the Export Family / Attribute Sets job before exporting products so that newly added Magento attribute options are registered in Akeneo.
Verify that the connector's auto-creation helper (ensureAkeneoOptionExists()) is enabled in module configuration.

Ensure Magento media directories have appropriate write permissions:
```
chmod -R 775 pub/media
chown -R www-data:www-data pub/media
```
For asynchronous media processing, verify that the Magento queue consumer is running:
```
php bin/magento queue:consumers:start product.export --max-messages=1000
```
Check the Import Log or Export Log for specific media URL errors.