# Common Issues

## Connection issues

<details>

<summary>OAuth connection fails or account doesn't appear after authorization</summary>

This usually happens when the popup is blocked or you authorized the wrong Mailchimp account. Close the popup, disable any popup blocker for the Coupler.io domain, and try connecting again. Make sure you're logged in to the correct Mailchimp account before clicking Connect — if you have multiple Mailchimp accounts, Mailchimp will use whichever one is currently active in your browser.

</details>

<details>

<summary>My Mailchimp audience doesn't appear in the audience dropdown</summary>

If you've just created a new audience in Mailchimp, try disconnecting and reconnecting your Mailchimp account in Coupler.io to refresh the list. If an audience still doesn't appear, check that your Mailchimp user role has access to that audience — Manager-level access is required.

</details>

## Permission errors

<details>

<summary>Error 403 — access denied</summary>

A 403 error means Coupler.io doesn't have permission to access the requested resource. This typically means your Mailchimp user role is too restricted. Mailchimp's **Viewer** role does not grant API access — you need at least **Manager** access. Ask your Mailchimp account admin to upgrade your role, then reconnect your account in Coupler.io.

</details>

## Missing data

<details>

<summary>Data is missing after a run completes</summary>

First, check that you selected the correct audience in the source settings — each audience-level entity only pulls from one audience at a time. If you're combining data from multiple audiences, you need separate sources in your data flow with the Append transformation applied. Also check whether any date filters are set that might be excluding records.

</details>

<details>

<summary>Some contacts are not appearing in the Audience export</summary>

By default, the **Audience (list of contacts)** entity returns all statuses. If you've applied advanced filters (e.g., filtering by status), some contacts may be excluded. Remove or adjust the advanced filters and re-run. Also note that archived contacts are not returned by the Mailchimp API.

</details>

<details>

<summary>Campaigns report shows different numbers than Mailchimp's dashboard</summary>

Mailchimp updates campaign stats over time as opens and clicks are tracked. If you pull data shortly after sending a campaign, the numbers will be lower than what you'll see after 24–48 hours. Re-run the data flow after the campaign has had time to accumulate engagement data. Also verify that your sent date filters aren't excluding campaigns you expect to see.

</details>

## Rate limits and timeouts

<details>

<summary>Data flow times out after 9 minutes</summary>

This is the most commonly reported issue for Mailchimp. It typically occurs with large audiences (100,000+ contacts) or when pulling the **Audience activity** entity, which can be very large. To work around this:

* Use **advanced filters** on the Audience entity to pull a subset of contacts (e.g., filter by status = subscribed)
* Use **date filters** on Campaigns and Automations to limit the time range
* Split large audiences across multiple data flows using status or tag filters
* For Mailchimp-to-BigQuery flows specifically, contact Coupler.io support — there may be additional options for large dataset handling

</details>

<details>

<summary>Error 409 — conflict error</summary>

A 409 error usually means the data flow ran while a previous run was still in progress, causing a conflict at the destination. Wait for any active run to finish before triggering another, or check if your schedule interval is too frequent for the size of the dataset being pulled.

</details>