> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/marketing/mailchimp/common-issues.md).

# 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>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coupler.io/sources/category/marketing/mailchimp/common-issues.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.