Troubleshooting

If something's broken, start here. The pages below catalog the errors most users hit, what they mean, and how to fix them.

Quick checks

Before diving into a specific page, confirm:

cbx version                    # should print a version, not an error
cbx llm cli test claude-code   # grounded audits need a working LLM CLI on PATH

Open Organisation → Cloud Profiles in the portal — at least one cloud profile should be linked (status: linked).

If any of these fail outright, jump to Install errors first.

cbx: command not found, broken Homebrew tap, Scoop bucket issues, version mismatches.

CloudFormation stack failures, role assumption errors, region mismatches, expired credentials.

LLM preflight, rule-pack resolution, permission errors, discovery-integrity warnings, CI integration.

If your issue isn't here:

Capture full output of the failing command (add -o json for the structured envelope, which includes the error code):
cbx <your-command> -o json 2>&1 | tee cbx-debug.log
Record your environment:
cbx version > cbx-env.txt
For AWS permission failures, cbx audit aws --diagnose also prints the exact IAM actions that were denied.
Open an issue on the project's issue tracker (link in your release email) and attach both files.

Do not include credentials, account IDs, or ARNs you'd rather not share publicly — redact cbx-debug.log before attaching.