Troubleshooting
Ordered recovery for installation, runner, credential, dispatch, and session failures.
Follow the section that matches the task you were doing. Keep the exact public error code and request ID; leave secrets and raw logs out of support requests.
Never send API keys, tokens, cookies, invitation links, recovery codes, config files, credential stores, or raw logs. Redact repository names and URL query strings from screenshots.
Installation and sign-in
| What you see | Recovery |
|---|---|
command not found: devboxes | Repeat Installation, add the install directory to PATH, then run devboxes --version. |
| A native npm package is missing | Reinstall without --omit=optional or --ignore-scripts, or use the native installer. |
Checksum verification failed | Stop. Retry the installer; never run the downloaded temporary file. |
| A managed device blocks the executable | Devboxes binaries are not yet publisher-signed. Do not bypass organization policy; ask the device administrator. |
| Connect asks for an organization | Run devboxes connect --organization <organization-id>. |
| HTTP 403 asks you to accept beta terms | Open app.devboxes.ai, choose Accept and continue, then retry. |
INVITE_ONLY_SIGNUP | Devboxes Alpha is invite-only — ask your organization admin for an invitation. Use the newest link with the invited email. |
Run stuck in Queued
Check these boundaries in order:
- Confirm the project's runner image finished building.
- Run
devboxes doctor. Fix registration or Docker warnings. - Run
devboxes credentials status. The selected model provider must appear locally or under Manage → Credentials → Model providers. - Start
devboxes listenand wait forListening for queued tasks..
| Runner symptom | Recovery |
|---|---|
machine_not_registered or heartbeat HTTP 401 | Run devboxes connect, then restart listen. |
listener_upgrade_required | Install the current devboxes version before reconnecting. |
Repeated Poll failed ( | Inspect the configured API URL with devboxes doctor --json, restore outbound HTTPS to it, then restart listen. |
container runtime is not reachable | Start Docker, confirm normal Docker commands work, then rerun doctor. |
| Machine was deleted | Run devboxes connect to revive the saved machine identity. Recreate local credentials if the encrypted store is no longer readable. |
After a crash, devboxes listen re-adopts valid running work and removes
terminal or reassigned leftovers. If reconciliation finishes but a container
remains, inspect it locally:
docker ps -a --filter name=firops-opencode-task
docker logs <container-name>Credential problems
| What you see | Recovery |
|---|---|
| Setup finds no local auth file | Use devboxes credentials setup --connect <provider> or pipe an API key to --api-key <provider>. |
| Sync says no credentials are configured | Run devboxes credentials setup, inspect credentials status, then sync again. |
| Sync skips another CLI's subscription | Connect a Devboxes-owned subscription with credentials setup --connect <provider>. |
doctor --live reports a rejected refresh | Reconnect that provider, restart listen, and rerun doctor --live. |
| Organization Disconnect is blocked | Finish or cancel active runs that already received the credential, then disconnect again. |
| Device store cannot be decrypted after machine deletion | Delete it only when the error instructs you, then run credentials setup to create a fresh store. |
Sync expands a credential to every runner. Review Managing credentials before repeating it.
Dispatch and live-session problems
| What you see | Recovery |
|---|---|
REPO_CONNECTION_REVOKED | Restore the GitHub App installation, then retry. |
| Repository credential is not configured or available | Reconnect it under Manage → Credentials → Repository, then update the project. |
| Run fails before the transcript starts | Follow the displayed repository, branch, provider quota, or rate-limit error, then rerun. |
| Provider auth fetch fails | Restore the provider in the local or organization store used by that runner, then restart listen when local. |
Session events are not updating
Reload the agent session. If it stalls again, test without a proxy or VPN that buffers streaming responses. Confirm another dashboard request succeeds.
For two-factor lockout, choose Email a code and use the newest code. There is no supported bypass.
Contact support
Choose Feedback / Support in the dashboard. Include the symptom or public
error code, request ID, run or machine ID, time and timezone, devboxes --version, browser version, and a redacted screenshot. If the dashboard is
unavailable, email hello@devboxes.ai.
Report suspected vulnerabilities privately to security@devboxes.ai, never in a public issue.