Buildkite agent "Unable to authenticate: 401" in CI

By Kaveh Alemi·Latchkey

The agent reached the Buildkite Agent API but the registration token it sent was rejected with HTTP 401. The connection works; the credential does not.

What this error means

The agent exits or refuses to register with "Unable to authenticate with Buildkite" and a 401 status. It never appears in the agents list.

2026-06-30 12:00:01 FATAL Unable to authenticate with Buildkite: POST
"https://agent.buildkite.com/v3/register": 401 Unauthorized

Common causes

The agent token is unset or wrong

The BUILDKITE_AGENT_TOKEN env var (or token config) is empty, contains a typo, or has surrounding whitespace, so registration is rejected.

The token was revoked or belongs to another cluster

The agent token was rotated in the Buildkite dashboard, or you used a token from a different organization or agent cluster than intended.

How to fix it

Inject the correct agent token from a secret

1. Copy the current Agent Token from Agents > Reveal Agent Token in the Buildkite dashboard.
2. Store it as a secret and expose it to the agent as BUILDKITE_AGENT_TOKEN, not in a committed file.
3. Restart the agent and confirm it registers.

export BUILDKITE_AGENT_TOKEN="${BUILDKITE_AGENT_TOKEN}"
buildkite-agent start

Rotate and update in one place after a revoke

If the token was rotated, update the single secret the agents read from so every agent picks up the new value on restart.

How to prevent it

• Keep the agent token in a secret store, never in the repository.
• Rotate the agent token on a schedule and update it in one place.
• Use per-cluster tokens so a leaked token has a limited blast radius.

Frequently asked questions

Related guides

References

• GitHub Actions documentation