Start with xcb doctor. It checks each provider build, the list of reviewed builds, and runs that didn’t finish cleanly, then names the next command to run.
The shell can’t find xcb, or runs the wrong one
Add ~/.local/bin to your PATH (export PATH="$HOME/.local/bin:$PATH"), then check command -v xcb. The installer warns when another xcb earlier on your PATH, such as an old copy, would run instead. The TypeScript compatibility CLI installs as xcb-compat.
doctor says a provider build can’t run
“found, but xcb can’t run this build yet” means the installed provider isn’t a supported build. “waiting for review before xcb runs it” means the provider updated itself; xcb keeps using the build it already checked until the new one is reviewed. Install a supported build, or wait for the review.
xcb found the wrong provider executable
xcb doctor --provider claude --executable /absolute/path/to/claudexcb keeps a private copy of the executable you name and uses it until you pin another.
An account needs signing in again
After a sign-in fails, xcb stops routing to that account, including after a restart, and xcb accounts marks it. Sign in again:
xcb accounts login <account>For Devin, run devin auth login and import the credentials again. Refreshing the model list or re-importing the same credentials doesn’t clear the mark.
No account can take a task
A task waits, or a route request fails with unavailable, when no account passes the routing checks. Check xcb accounts for usage limits, disabled accounts, and accounts that need signing in; xcb models for models; and xcb models route --task "…" for the route xcb would pick.
A task finished with no reply and no changes
Send it again on another provider by starting the prompt with Use Claude or Use Codex, or pin provider in a route request. To keep tasks off one account for a while, run xcb accounts disable <account>.
A run didn’t finish cleanly
When xcb can’t confirm that a provider stopped, it keeps that account held and doesn’t retry. xcb doctor reports the run.
xcb recover # list runs that didn't finish cleanly
xcb recover <run-id> # show what recovery would do
xcb recover <run-id> --yes # confirm the process is gone and release the accountRecovery checks that the provider’s processes are gone before it releases the account, and it never applies unpublished command changes. Do not delete lock files or state to get an account back; a missing process ID or an elapsed timer doesn’t prove the provider stopped.
After an upgrade, xcb says another build owns the supervisor
The previous build’s supervisor is finishing its running tasks. Wait for it to exit (on macOS, xcb service status shows “supervisor idle”), restart your terminals, and open xcb again. Queued tasks stay saved. See after an upgrade.
macOS blocks project folders
When the login service runs xcb in the background, macOS may block it from folders such as Documents, Desktop, or Downloads. xcb service status then reports “xcb can’t open files in ~/Documents: macOS access is off for xcb.” Turn on xcb under that folder in System Settings › Privacy & Security › Files & Folders, or open the pane directly:
open 'x-apple.systempreferences:com.apple.preference.security?Privacy_FilesAndFolders'Claude won’t start on Linux
“native OS confinement is not qualified on this platform” means the sandbox checks haven’t run on this machine, are older than 30 days, or no longer match its bwrap or namespace settings. Run the Linux sandbox checks again.
config.json is rejected
“config.json is incompatible with this xcb build” means the file has a key or value this build doesn’t accept, often after going back to an older release. Fix the key, or remove it to use the default; the configuration reference lists valid values.
Get help
Search or open an issue on GitHub, and include the output of xcb --version and xcb doctor. Report security problems privately through the security policy.