oven-sh/bun · critical · Error

Buildkite token not found: set BUILDKITE_AGENT_TOKEN or gran

Error message

Buildkite token not found: set BUILDKITE_AGENT_TOKEN or grant this machine access to the buildkite agent-token secret

What it means

Thrown by the CI agent bootstrap script when it cannot find a Buildkite agent token anywhere. The script resolves the token from (in order) the BUILDKITE_AGENT_TOKEN env var, AWS Secrets Manager, Azure KeyVault, a cloud VM metadata tag 'buildkite:token', and finally a macOS buildkite-agent.cfg file. When every source is empty and there is no macOS config file, the agent cannot authenticate to Buildkite, so startup aborts.

Source

Thrown at scripts/agent.mjs:302

  async function start() {
    const cloud = await getCloud();

    let token = getEnv("BUILDKITE_AGENT_TOKEN", false);
    if (!token && cloud === "aws") {
      token = await getAwsSecret(BUILDKITE_TOKEN_SECRET);
    }
    if (!token && cloud === "azure") {
      token = await getAzureSecret(AZURE_KEYVAULT, AZURE_TOKEN_SECRET);
    }
    // Images baked before the secret stores existed only had the tag.
    if (!token && cloud) {
      token = await getCloudMetadataTag("buildkite:token");
    }

    const hasCfg = isMacOS && existsSync(cfgPath);
    if (!token && !hasCfg) {
      throw new Error(
        "Buildkite token not found: set BUILDKITE_AGENT_TOKEN or grant this machine access to the buildkite agent-token secret",
      );
    }

    let shell;
    if (isWindows) {
      // Command Prompt has a faster startup time than PowerShell.
      // Also, it propogates the exit code of the command, which PowerShell does not.
      const cmd = which("cmd", { required: true });
      shell = `"${cmd}" /S /C`;
    } else {
      const sh = which("sh", { required: true });
      shell = `${sh} -elc`;
    }

    const distroVersion = getDistroVersion();
    const flags = ["enable-job-log-tmpfile", "no-feature-reporting"];
    const options = {

View on GitHub (pinned to 8c5296ac45)

Solutions

1. Export BUILDKITE_AGENT_TOKEN in the shell or pipeline environment before running the script
2. Grant the machine/role read access to the Buildkite agent-token secret in AWS Secrets Manager (or the configured Azure KeyVault secret)
3. For cloud VM images, set the 'buildkite:token' instance metadata tag on the image
4. On macOS agents, ensure buildkite-agent.cfg exists at the path the script checks (cfgPath)

Example fix

// before
$ bun scripts/agent.mjs
Error: Buildkite token not found: set BUILDKITE_AGENT_TOKEN or grant this machine access to the buildkite agent-token secret

// after
$ export BUILDKITE_AGENT_TOKEN=bkua_xxx
$ bun scripts/agent.mjs

import { existsSync } from 'node:fs';
const cfgPath = process.env.BUILDKITE_AGENT_CFG_PATH ?? '/usr/local/etc/buildkite-agent/buildkite-agent.cfg';
const hasToken = Boolean(process.env.BUILDKITE_AGENT_TOKEN);
const hasCfg = process.platform === 'darwin' && existsSync(cfgPath);
if (!hasToken && !hasCfg) {
  console.error('agent bootstrap will fail: no BUILDKITE_AGENT_TOKEN, secret-store grant, metadata tag, or macOS cfg');
  process.exit(1);
}

When it happens

Trigger: Running scripts/agent.mjs on a Linux or Windows CI host where BUILDKITE_AGENT_TOKEN is unset, the machine has no grant for the agent-token secret in AWS Secrets Manager or Azure KeyVault, and (on cloud VMs) the 'buildkite:token' metadata tag was never baked into the image. The cfg-file fallback only applies on macOS (hasCfg = isMacOS && existsSync(cfgPath)).

Common situations: A new CI machine or docker image was never granted the buildkite agent-token secret; the secret was renamed or deleted in the secret store; older VM images baked before the secret stores existed only carry the metadata tag; a local dev run without the env var set.

Related errors

• Azure secret not found: ${name}
• BUILDKITE_AGENT_TOKEN not set and no existing buildkite-agen
• GITHUB_TOKEN environment variable is required
• [azure] Unsupported OS: ${os}
• ${res.status} ${job.raw_log_url}

AI-assisted analysis of oven-sh/bun@8c5296ac45 (2026-08-16). Data as JSON: /api/errors/3ecb9d1fbf015c5c. Report an issue: GitHub.