Troubleshooting ​

Each section starts with what you see, explains why, and says how to fix it. Messages in code blocks are what Bumpkit prints; names, numbers and SHAs in them are examples.

bumpkit gate exits 0 on pass, 1 on needs_approval or fail, and 2 when it can't decide. See CLI Reference.

The gate fails ​

Symptom. The gate prints a BLOCKED: headline and a BLOCKED reason, the job exits 1, and the GitHub check concludes failure:

BLOCKED: Adds a private key (services/billing/keys.go:3)
Fix the blocking findings below; approval can't override them.
Version: 1.4.2 → 1.5.0 (minor). Derived from Conventional Commit types without a language model.
Committed by Dana Lee
Written with Claude Code · 95% (co-author trailer in 1 of 1 commit; measured on 40 verified releases in this workspace).
  BLOCKED · Secrets block the release: Adds a private key (services/billing/keys.go:3)
      What to do: Fix the finding and push. If it is a false positive, mark it so on the release page. An owner, admin or policy admin can break glass on the check page in the dashboard if the policy allows it. https://bumpkit.dev/docs/explanations#gate-blocked-finding

Why. Something in the policy forbids the change outright. The rule tells you which. The log shows its label; --json shows the rule name:

Fix. Approval can't clear a fail. Change the code (remove the secret, upgrade the dependency, back-port the fix), make the required check pass, or ask the person who denied it. If the finding is a false positive, report it so it can be suppressed (see Finding feedback). If the change must ship now, an owner, admin or policy admin can override that one commit with a reason.

The gate needs approval ​

Symptom.

NEEDS APPROVAL: Needs a human approval from sam, priya
Approve the pull request; the gate re-checks automatically.
Version: 1.4.2 → 1.5.0 (minor). Derived from Conventional Commit types without a language model.
Committed by Dana Lee
Written with Claude Code · 95% (co-author trailer in 1 of 1 commit; measured on 40 verified releases in this workspace). Agent changes, and changes no person is confirmed to have written, need a person's approval.
  NEEDS APPROVAL · Agent or unverified changes to billing need approval: Changes billing code (2 files, 10 lines). Needs 1 approval from sam, priya (has 0)

The job exits 1. With the GitHub App the check concludes action_required.

Why. A rule that needs a person was triggered: a require_approval rule, a guarded blast radius area, a missing back-port under backports: approve, a hotfix that carries a feature or too many files, a check too large to read in full, or require_checks without the GitHub App. The headline says whose approval it needs, and the end of a rule's message says how many approvals it has.

Fix. Ask a qualifying reviewer to approve the pull request's latest commit on GitHub, or vote in Slack or on the dashboard. The gate runs again on its own with the GitHub App. With the Action alone, the workflow must also run on pull_request_review (see below). See Approvals.

An approval didn't count ​

Symptom. Someone approved, but the gate still says NEEDS APPROVAL, or the reason says (has 0).

Why. On GitHub, Bumpkit takes each reviewer's latest review (comments are skipped) and counts it only when all of these hold:

The agent check reads the login, so a person whose GitHub login looks like an agent's isn't counted either.

Other reasons an approval is missed:

• The gate didn't re-run. Re-run the Bumpkit release gate check, or the CI job that runs bumpkit gate.
• Teams or CODEOWNERS can't be checked. Without the Bumpkit GitHub App, the reason ends with "team membership can only be checked through the Bumpkit GitHub App" or reads "CODEOWNERS can only be checked through the Bumpkit GitHub App". Install the App, or list GitHub logins in approvers.
• The token can't read reviews. On GitLab CI, the default CI_JOB_TOKEN can't read merge request approvals. Set GITLAB_TOKEN or BUMPKIT_GITLAB_TOKEN with the api scope. See Release Gate.
• A Slack or dashboard vote was refused. Bumpkit tells the voter why, privately. See Who can vote.

Fix. Ask a different qualifying person to approve the latest commit. After every push, approve again.

Bumpkit couldn't decide ​

Symptom. bumpkit gate prints an error instead of a decision and exits 2, or the GitHub check fails with the title "Bumpkit couldn't check this pull request". Common causes:

Bumpkit API error (HTTP 503): Auth service temporarily unavailable.

Post "https://bumpkit.dev/v1/gate": dial tcp: lookup bumpkit.dev: no such host

Why. The gate fails closed: when Bumpkit can't finish a decision, the change doesn't pass. That covers an unreachable API, a server error, a GitHub API error while reading reviews or CI results, a policy Bumpkit couldn't read from the base branch (see the base isn't a branch or tag).

on_error decides what such an error means. With the default fail, the CLI exits 2 and the App's check concludes failure. With on_error: pass, the gate is advisory: the CLI prints the error, then passes and exits 0, and the App's check concludes neutral (except with require_check_apps set, which always fails closed):

Bumpkit couldn't decide, passing because on_error is pass: Bumpkit API error (HTTP 503): Auth service temporarily unavailable.

on_error never rescues an invalid bumpkit.yml; see the policy is invalid.

A check that couldn't run ​

Some checkers report that they couldn't finish, instead of guessing. The gate then waits for a person rather than passing silently:

Fix. Re-run the job or the check; most of these are temporary. If the API is unreachable, check BUMPKIT_API_URL (or the Action's api-url input) and your network or proxy. If a checker stays unavailable, a reviewer can approve the change once they have looked. See Cross-Repo Impact for the Beta cross-repo check.

The policy is invalid ​

Symptom. The CLI prints a bumpkit.yml: error and exits 2. The GitHub check fails with the title "Invalid bumpkit.yml" and shows the error. POST /v1/gate answers 400 with code INVALID_POLICY. For example:

bumpkit.yml: gate.on_error must be fail or pass
bumpkit.yml: gate.block_on: unknown kind "secrets" (use secret, data_loss, security_regression, breaking, contract_breaking, version_mismatch, cve_reachable, compatibility_break)
bumpkit.yml: gate.vulnerabilities must be high, medium or low
bumpkit.yml: gate.security_alerts must be critical, high, medium or low
bumpkit.yml: gate.hotfix.backports must be block, approve or off
bumpkit.yml: gate.hotfix.review_within must be a duration like 24h or 72h
bumpkit.yml: gate.require_checks has an empty name
bumpkit.yml: gate.deploy.require must be pass or approved
bumpkit.yml: line 4: count must be between 1 and 10
bumpkit.yml: line 3: when must be always, agent or agent_or_unknown

A misspelled or unknown key also fails, with the YAML parser's message naming the line.

Why. Bumpkit never falls back to a default when your policy has a mistake. If it did, a typo could turn the gate off. The gate fails closed, even with on_error: pass. If the App can't read the file at all, the check fails with the title "Couldn't read bumpkit.yml".

Fix. Correct the line the error names. The gate reads the policy from the base of the pull request, so a fix in the same pull request doesn't apply yet. Try the edited file first with:

bumpkit gate --policy bumpkit.yml

--policy checks the file locally. When the Bumpkit GitHub App is installed on the repository, the decision itself still uses the base branch's copy. Then merge the fix on its own. See Invalid policy.

A compatibility pair says not checked ​

Symptom. A pair in the compatibility matrix shows not_checked.

Fix. Read the reason on the pair. Not checked means Bumpkit has no complete evidence, and it never means compatible. Turn on contract_checks and version_consistency if the reason names them. Then run a release check from one version tag to the next, inside the range. Checks recorded before compatibility_matrix was on don't count.

The gate can't read the policy ​

Symptom. With the Bumpkit GitHub App installed on the repository, bumpkit gate answers 503 with code POLICY_UNAVAILABLE:

Bumpkit couldn't read bumpkit.yml from the base branch of acme/api with the GitHub App, so the gate fails closed. Run the gate again.

Why. When the App is installed on the repository for your workspace, Bumpkit reads bumpkit.yml itself: from the base commit of a pull request into the default branch, and from the default branch otherwise. If GitHub can't return the file, the gate fails closed rather than trust a policy it couldn't check.

Fix. Run the gate again; it is usually a temporary GitHub error. See The policy comes from the base.

The org policy can't be read ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: org_policies.

Symptom. The GitHub check fails with the title "Couldn't read the org policy". The API answers 503 with code ORG_POLICY_UNAVAILABLE and one of these messages:

Bumpkit couldn't read the org policy from acme/.github (the Bumpkit GitHub App isn't installed on it), so the gate fails closed.
Bumpkit couldn't read the org policy from acme/.github (it has no bumpkit.yml on its default branch), so the gate fails closed.
The org policy (version 7) doesn't parse, so the gate fails closed: org policy: locked must be a list of gate keys

Why. Your workspace has an org policy, stored in Bumpkit or in a config repository, and Bumpkit couldn't load it. Rather than gate with only the repository's rules, the decision fails. When the policy lives in a config repository, the reasons in brackets are: the GitHub App isn't set up, isn't installed on it, is installed for another workspace, GitHub didn't grant access, GitHub returned an error, or the repository has no bumpkit.yml on its default branch.

The CLI treats this 503 like any other API error, so a repository with on_error: pass passes in CI. Lock on_error in the org policy if that isn't what you want.

Fix. Install the Bumpkit GitHub App on the config repository from the same workspace, add or fix its bumpkit.yml, or save a corrected version of the stored policy. Then re-run the check. See Org Policies & Freezes.

Rate limits ​

Symptom. The API answers 429:

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Minute rate limit reached. 120 requests allowed per minute.",
    "suggestion": "Wait for the rate-limit window to reset, then retry."
  }
}

The error also carries explanation, next_step and docs_url.

Why. Operational per-minute limits protect the service and are separate from billing, which is 1 credit = 1 release check = $0.10, with 60 free credits each month and no seat or repository limits. A workspace's limit is shared by all its keys. Responses carry X-RateLimit-* headers and Retry-After (seconds until the minute window resets). A few endpoints have their own limits and send their own Retry-After, for example POST /v1/cli/login ("Too many sign-in requests from this address. Try again in a minute.", Retry-After: 60) and POST /hooks/errors/{token} ("Too many error reports for this source. Batch events, up to 500 per request.", Retry-After: 60). The full list is in Rate limits.

Fix. Wait for the reset, or batch work into fewer calls.

No tag to start from ​

Symptom.

no tag to start from; pass --base

bumpkit hotfix version says no version tag to start from; pass --from, and bumpkit deploy warns bumpkit deploy: no earlier tag, so no commits are sent; pass --base to attribute errors to commits.

Why. Without a flag, Bumpkit starts a release from the latest tag reachable from HEAD. A new repository, or a checkout without tags, has none.

Fix. Pass the start yourself: --base for check, gate and deploy, and --from for analyze, changelog, bump and hotfix version (they print the same pass --base message, but their flag is --from). Or tag your first release, for example git tag v0.1.0 && git push origin v0.1.0. A release train can't be cut until the repository has a release tag like v1.0.0.

A multi-repo train won't start a step ​

Cause. The step says what holds it. MULTI_TRAIN_ORDER_NEEDED means Bumpkit can't prove the order: a repository isn't on the service map, the graph couldn't read it all, a cycle exists, or nothing connects the repositories. MULTI_TRAIN_HELD means an earlier step hasn't released.

Fix. Run bumpkit train multi show TRAIN. Have a person set the order on the train's page, or release the earlier step first. See Release across repositories.

Shallow checkout ​

Symptom. In CI, the gate or check fails with:

v1.4.2 is not a commit, tag or branch in .

or you see no tag to start from; pass --base although the repository has tags. Back-port detection may warn Bumpkit couldn't check for hotfix fixes missing from this release: followed by the git error.

Why. Many CI systems clone only the latest commit. Bumpkit needs the base commit, the tags and the history between them. bumpkit gate fetches a missing base itself; bumpkit check and the other commands don't.

Fix. Check out full history:

Missing API key ​

Symptom.

not signed in: run `bumpkit login`, or set BUMPKIT_API_KEY

The API answers 401 with MISSING_API_KEY ("No API key provided. Include your key in the x-api-key header."), INVALID_API_KEY or REVOKED_API_KEY.

Why. The CLI found no key in BUMPKIT_API_KEY or in its config file from bumpkit login, or the key was mistyped, revoked or expired. In GitHub Actions, secrets aren't passed to workflows triggered from forks.

Fix. On your machine, run bumpkit login. In CI, add the key as a secret named BUMPKIT_API_KEY and pass it to the step. Run bumpkit whoami to see which workspace and key the CLI uses. For the gate, a missing key counts as "couldn't decide": it exits 2, or passes under on_error: pass.

Feature not enabled ​

Symptom. A command or endpoint for a Beta feature answers 403 with code FEATURE_EARLY_ACCESS. The CLI prints only the message:

Error: Agent scorecards is in early access. Request access at https://dashboard.bumpkit.dev/early-access?feature=agent_scorecards

A feature that is off answers 404 with code NOT_FOUND:

Error: Bumpkit API error (HTTP 404): Route not found.
Next: Check the method, path and id against the API reference. A Beta feature your workspace doesn't have yet usually answers FEATURE_EARLY_ACCESS instead, with a link to request it. https://bumpkit.dev/docs/explanations#not-found

Some commands check first and say so directly, for example:

Error: Intelligent rollback is not enabled for this workspace

Why. Beta features are in early access: they are on only for the workspaces they have been rolled out to so far. Its dashboard page or tab shows an early-access page instead, with a Sign me up for early access button. A feature that is off for everyone answers as if the route doesn't exist. MCP tools for a feature your workspace doesn't have don't appear at all.

Fix. Open the link in the message and sign up for early access; you get an email when it's on for your workspace. Run bumpkit features to list what is on. For the gate, a 403 or 404 counts as "couldn't decide".

The GitHub check stays in progress ​

Symptom. Bumpkit release gate shows "Waiting for ci/test" and doesn't finish.

Why. The policy has require_checks. When a required check has started on the commit but hasn't finished, the App waits, then decides as soon as it completes. A check that is stuck queued or running keeps the gate waiting.

Fix. Finish or re-run the stuck CI check, then re-run Bumpkit release gate if it doesn't update. Names in require_checks match check and status names without regard to case. A required check that never started on the commit isn't waited for: the gate fails it with "ci/test didn't run on this commit."

The GitHub check failed after retries ​

Symptom. Bumpkit release gate fails with "Bumpkit couldn't finish this check".

Why. Bumpkit hit an error each time it tried to check the commit, for example while GitHub was unavailable, so the gate fails closed rather than letting the pull request through unchecked.

Fix. Push a commit or re-run Bumpkit release gate on GitHub to try again. The Queued, running, retrying and failed pull request checks panel on the Checks page, bumpkit checks queue and the checks_queue MCP tool show checks that are still retrying.

GitHub Enterprise Server won't connect or report ​

• "The host must be your GitHub Enterprise Server's https address on a public host." Give the plain address, like https://github.acme.example, on port 443. IP addresses, other ports and names like .internal or .local are refused. For github.com, install the Bumpkit GitHub App.
• No status appears on the pull request. Check that your server can be reached from the public internet, and that the token has the repo scope. Bumpkit refuses to call a host that resolves to a private address.
• The webhook delivery shows 400. Set Content type to application/json on the webhook.
• The webhook delivery shows 401. The secret on the webhook doesn't match. Remove the connection and add it again to get a new one.