# Common Issues

## Connection issues

<details>

<summary>Invalid credentials or authentication failure</summary>

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.

</details>

<details>

<summary>Instance URL not recognized</summary>

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.

</details>

## Missing data

<details>

<summary>Products are missing from the export</summary>

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.

</details>

<details>

<summary>Attribute values are empty or null</summary>

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.

</details>

<details>

<summary>Family variants or categories return no records</summary>

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.

</details>

## Permission errors

<details>

<summary>403 Forbidden when accessing certain entities</summary>

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.

</details>

## Data discrepancies

<details>

<summary>Product count in Coupler.io doesn't match Akeneo UI</summary>

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.

</details>

## Rate limits

<details>

<summary>Data flow times out or returns partial data on large catalogs</summary>

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.

{% hint style="warning" %}
Akeneo Cloud (Growth and Enterprise editions) generally have higher rate limits than self-hosted Community Edition instances.
{% endhint %}

</details>