Common Issues

Connection issues

Invalid credentials or authentication failure

Akeneo uses a combination of client ID, client secret, username, and password — not just an API key. Double-check all four fields in your data flow settings. A single incorrect character will cause authentication to fail.

Also confirm that the API connection in Akeneo (System → API connections) is still active and hasn't been regenerated since you set up the data flow.

Instance URL not recognized

Make sure you're entering the full base URL of your Akeneo instance, including https://. For cloud instances it typically looks like https://yourstore.cloud.akeneo.com. Do not include a trailing slash or any path after the domain.

Missing data

Products are missing from the export

Akeneo only returns products the API connection's role has permission to read. Check the role assigned to your API connection under System → API connections → Edit and confirm it has read access to products and the relevant catalog scope.

Also note that disabled products are included in the API response by default — if you're seeing fewer records than expected, check whether filters are being applied upstream in Akeneo.

Attribute values are empty or null

Attribute values in Akeneo are locale- and channel-scoped. If an attribute is localizable or scopable, its value will only appear for the specific locale/channel combinations where it has been filled in. Missing values simply mean the field hasn't been populated in Akeneo for that scope — this is not a Coupler.io issue.

Family variants or categories return no records

If you haven't created any family variants or populated your category tree in Akeneo, these entities will return empty results. Verify the data exists in your Akeneo instance before troubleshooting the connection.

Permission errors

403 Forbidden when accessing certain entities

The API connection role in Akeneo controls access per entity type. If you can pull Products but not Channels or Locales, the role may be missing read permissions for those entities. Go to System → Roles in Akeneo, find the role tied to your API connection, and enable read access for the entities you need.

Data discrepancies

Product count in Coupler.io doesn't match Akeneo UI

The Akeneo UI may show counts that include product models (parent records for variants), while the API may return them separately or combined depending on your query. Check whether you need both the Products and Family variants entities to capture the full picture.

Also confirm that the API role's catalog scope isn't restricted to a subset of categories, which would reduce the visible product set.

Rate limits

Data flow times out or returns partial data on large catalogs

Akeneo's API enforces rate limits, especially on Community Edition instances. Very large catalogs (tens of thousands of products with many attribute values) can hit these limits during a full sync.

If you're experiencing timeouts, try splitting your data flow into multiple sources — for example, one flow for Products and a separate flow for Attributes and Families. This reduces the load per run.

Akeneo Cloud (Growth and Enterprise editions) generally have higher rate limits than self-hosted Community Edition instances.