> 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/buildkite/common-issues.md).

# Common Issues

## Connection issues

<details>

<summary>API token is rejected or authentication fails</summary>

Double-check that you've copied the full API token from Buildkite — no extra spaces or missing characters. Also confirm the token hasn't been revoked in **Personal Settings → API Access Tokens**. If you generated the token a while ago and it no longer works, create a new one and update it in your Coupler.io data flow settings.

</details>

<details>

<summary>Data flow connects but returns no data</summary>

This usually means the API token doesn't have the required read scopes for the entity you selected. In Buildkite, open the token settings and verify that it includes `read_builds`, `read_pipelines`, or the relevant scope for your entity. Regenerate with the correct scopes if needed.

</details>

## Missing data

<details>

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

Check your **start date** setting. If the start date is set too recently, older builds won't be included. Use the date picker to move the start date back further. Also verify that the builds you're looking for exist in the specific pipeline and organization you've selected.

</details>

<details>

<summary>Analytics suites entity returns empty results</summary>

Buildkite Test Analytics must be actively configured in your organization and have data ingested before this entity returns results. If you've only recently set up Test Analytics, there may not be enough data yet. Check in the Buildkite dashboard under **Analytics** to confirm suite data is present.

</details>

<details>

<summary>Only seeing data for some pipelines, not all</summary>

Your API token may only have access to specific pipelines or organizations. Buildkite token scopes can be restricted to particular resources. Confirm the token has org-level read access, or generate a new token with broader permissions.

</details>

## Permission errors

<details>

<summary>403 Forbidden error when pulling certain entities</summary>

This means your API token doesn't have permission to access that resource. Cluster tokens, access token details, and some org-level entities require elevated permissions. Review the required scopes for the entity in Buildkite's API documentation and update your token accordingly.

{% hint style="warning" %}
Organization-level entities like Organizations clusters tokens may require a token with admin-level scopes. Be careful when sharing data flows that include these entities.
{% endhint %}

</details>

## Data discrepancies

<details>

<summary>Build counts in Coupler.io don't match the Buildkite dashboard</summary>

The Buildkite dashboard may show builds that are still running or in a `scheduled` state at the time of your export. Coupler.io captures a point-in-time snapshot — builds that started after your data flow ran won't appear until the next run. Also check that your start date captures the same time range you're comparing against in the dashboard.

</details>

<details>

<summary>Build duration looks incorrect</summary>

Build duration is derived from `started_at` and `finished_at` timestamps. If a build was blocked or waited in a queue before running, the wall-clock time will differ from actual execution time. Use `started_at` rather than `created_at` as the start point for duration calculations.

</details>

## Rate limits

<details>

<summary>Data flow fails with a rate limit error</summary>

Buildkite enforces API rate limits per token. If you're running multiple data flows using the same API token and hitting limits, consider spreading out your scheduled runs. Alternatively, use a token associated with a service account rather than a personal user account to get a higher rate limit allowance.

</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/buildkite/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.