Troubleshooting

Start with verified context

bworlds --version
bworlds auth status
bworlds build info BUILD_SLUG

These 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 tokens.

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. Use --force when replacing an existing CLI-managed clone. 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 --json

If the start response itself was lost, repeat the start command with the same --request-id. The server returns the existing run without charging again.

Repository access fails

Confirm that the Build has a connected repository and that the BWorlds GitHub App is authorized on it. Clone and refresh need read access. Push needs write access and --confirm.

The CLI rejects repository URLs with embedded credentials and keeps the short-lived credential out of the saved Git remote. Do not enable GIT_TRACE, GIT_TRACE_CURL, or GIT_CURL_VERBOSE around repository commands.

If a push fails after the CLI created the local commit, rerun the same command with --confirm. The CLI detects the pending commit, obtains a fresh credential, and pushes without committing twice. It preserves existing commit metadata; actor trailers are guaranteed only on a new commit the CLI creates.

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.