> 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/project-management/circleci/common-issues.md).

# Common Issues

## Connection issues

<details>

<summary>Authentication fails after entering my API token</summary>

Double-check that you're using a **personal API token**, not an OAuth token or a project token. Generate one at CircleCI → User Settings → Personal API Tokens. Make sure you copy the full token without leading or trailing spaces.

</details>

<details>

<summary>Connection succeeds but no data is returned</summary>

This usually means the authenticated user doesn't have access to the org or project you're querying. Confirm that the account associated with the API token is a member of the organization and has at least read access to the relevant projects.

</details>

## Missing data

<details>

<summary>Insights metrics or Insights branches show no rows</summary>

Insights data requires that pipelines have run within the reporting window CircleCI uses on their end. If the project is new or hasn't had recent activity, insights may be empty. Also verify that the `project_id` parameter matches the correct project — a mismatch will silently return nothing.

</details>

<details>

<summary>Jobs entity returns no data</summary>

The Jobs entity requires a job number. If you haven't specified one, Coupler.io will attempt to auto-fetch it from Workflow jobs. Make sure the Workflow jobs entity is included and has data, or manually provide the job number from your pipeline URLs.

</details>

<details>

<summary>Historical data is missing before a certain date</summary>

CircleCI's API has retention limits on older pipeline data depending on your plan. Data beyond the retention window won't be returned regardless of the start date you set. Check your CircleCI plan's data retention policy.

</details>

## Permission errors

<details>

<summary>403 Forbidden error when fetching Contexts</summary>

Context data is restricted to organization admins in many CircleCI plans. If your account is not an org admin, you'll receive a 403. Ask your CircleCI org admin to either grant elevated permissions or pull context data using their token.

</details>

<details>

<summary>Cannot access data for a specific project</summary>

Confirm that the API token belongs to a user who has been granted access to that project in CircleCI. Private projects require explicit project membership — org membership alone may not be sufficient.

</details>

## Data discrepancies

<details>

<summary>Pipeline counts in Coupler.io don't match what I see in the CircleCI dashboard</summary>

The most common cause is the start date cutoff. The CircleCI dashboard may show all-time data while your Coupler.io data flow is scoped to a specific start date. Adjust the start date or check whether the dashboard is applying its own date filters.

</details>

<details>

<summary>Workflow duration looks different from what CircleCI reports</summary>

Coupler.io surfaces raw `created_at` and `stopped_at` timestamps. If you're calculating duration yourself (e.g., in a spreadsheet formula), make sure both fields are being parsed as timestamps in the same timezone. CircleCI timestamps are in UTC.

</details>

## Rate limits

<details>

<summary>Sync is slow or times out on the first historical load</summary>

CircleCI rate-limits API requests. Large organizations with many pipelines will take longer on the initial sync because Coupler.io needs to paginate through all historical records from your start date. Set a more recent start date to reduce the volume of data on the first run, then adjust once everything is working.

</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/project-management/circleci/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.