Troubleshooting
Diagnose identity, access, billing, network, and repository failures.
Start with verified context
bworlds --version
bworlds auth status
bworlds build info BUILD_SLUGThese three commands catch the most common mismatch: a valid identity without the expected Workspace Membership, or the wrong Build slug.
Identity, access, and target
| Exit code | What it means | What to do |
|---|---|---|
3 | Session or personal token is missing, expired, or revoked. | Sign in again, or replace the automation secret. |
4 | The identity is signed in but lacks the required access. | Check Workspace Membership. Token management needs a user session. |
5 | The target is absent or outside your Workspaces. | Check the Build slug and your Memberships. Do not probe other slugs. |
7 | The Workspace cannot cover the metered operation. | Stop and ask the Workspace Owner to review credits. |
The full table, including network and server codes, is in Agents and automation.
A command waits for input in CI
Supply every required argument and --confirm flag. A plain auth login prints a Device Approval code and URL even on a headless machine; approve it from a signed-in device. Use BWORLDS_TOKEN in CI.
The Audit stopped reporting
An Audit run belongs to the server. A local timeout or a dropped connection does not cancel it. Read it back by its identifier:
bworlds audit status AUDIT_RUN_ID --jsonIf the start response itself was lost, repeat the start command with the same --request-id. The server returns the existing run without charging again.
A verification cannot read the repository
A Control or exploratory claim that needs code requires a connected repository the BWorlds GitHub App can reach. bworlds build info <slug> reports GitHub: not connected when the Build has none. Keep the Audit Finding open until the required evidence is accessible; do not close it manually because verification cannot run.
When it reports GitHub: connected to <owner>/<repo>, check two things. The BWorlds GitHub App must still be authorized on that repository; the Builder grants it from the app. And that must be the repository the app actually ships from, which is worth comparing against your own checkout's origin, because a Builder can connect the wrong one.
A recheck reads that repository's default branch, never a feature branch and never a pull request. A recheck that still fails on code you believe you fixed is usually a change that has not been merged yet.
A clone left by an older version
Earlier versions of the CLI kept a managed clone under your temporary directory. Nothing writes there now. List what is left before removing anything:
ls -d "${TMPDIR:-/tmp}"/bworlds-cli-*Each directory is a plain clone holding no BWorlds credential, so delete the ones you recognize however you normally delete a directory. Your temporary directory is cleared on reboot on most systems, so leaving them costs only disk.
A command says your version is unsupported
Exit code 11 means the API serves a minimum CLI version and this binary sits below it. The message names that minimum and the command that installs a newer one. Run that command, then rerun the original. No retry helps before the upgrade, and nothing was charged.
Read the current minimum at any time:
curl -fsS https://api.bworlds.co/api/cli/config | jq -r '.minimum_cli_version'Documentation and command disagree
Compare bworlds --version with the version at the top of the CLI command reference. Install the matching binary or update the pinned version. Reference drift is checked in CI.