Troubleshooting agents
Diagnose installation, authentication, models, credit, desktop profiles and usage across coding clients.
Start with the right deployment
Run tokamak-stag for staging, tokamak-dev for development and tokamak for production. Each has separate saved state. The commands below use the production spelling; substitute yours.
tokamak status
tokamak auth status
tokamak launch codex --model YOUR_MODEL_ID --checkstatus checks the live connection. --check is offline: it does not install, update, write configuration, start the client or validate the model against the server. For Cowork, omit --model.
Command not found or Windows error 193
Reopen your terminal after installation and verify that the CLI and required client executable are on PATH. Oh My Pi, Jan Agent and desktop apps must be installed separately. Other CLI adapters can install their supported npm package when missing.
Current Tokamak resolves Windows npm batch shims rather than their extensionless Unix scripts. If an older CLI reports error 193, update the matching deployment's CLI with tokamak update, then retry. An executable starting successfully does not prove model inference works.
Authentication or account mismatch
Authenticate again with your deployment's CLI. Check the API origin and the organization bound to the credential; switching the web workspace does not move a key to another organization. Desktop apps need their launcher rerun after key rotation or account changes, then a full app restart.
Keep native account requirements in mind: Droid may need a Factory account, Copilot's GitHub features may need GitHub authentication, and hosted desktop features retain their vendor requirements.
Messages after signing in
Login ends with a short readiness check. Each warning names its fix:
| Message | What to do |
|---|---|
No models are available to this account yet | Ask your organization's administrator to enable a model. |
No credits yet, so requests will be refused | Add credits from the linked Billing page. Only an enforced wallet refuses requests at a zero balance. |
Your organization's wallet is frozen | Requests are refused until the wallet is unfrozen; the message links to Billing and states the reason when there is one. |
Organization: not recorded for this login | Run tokamak auth again to choose which organization is billed. |
No default model is saved; launching without one | Pass --model <catalog-id>, or launch once in an interactive terminal to choose and save a default. |
Your default model '…' is not in the model catalog | The saved default was retired or belongs to another environment. In a terminal the launch asks you to choose a new one; otherwise pass --model <catalog-id>. Without it the agent fails with failed to select provider model: model not found in accessible providers. |
Select a model with --model <catalog-id> | This agent needs a model and none was given or saved; pass --model. |
Set TOKAMAK_DEBUG=1 to see the details a normal run hides: the API key suffix and config path after login, the installer's download details, and every launch step. tokamak launch --debug shows the launch steps for a single launch.
Unknown model or unsupported API
Use --model to select an exact catalog model, and match its API to your client:
| API | Clients |
|---|---|
| Messages | Claude Code, Claude Cowork |
| Responses | Codex CLI, Codex App, Copilot CLI, Oh My Pi, Pi |
| Chat Completions | OpenCode, DeepSeek Harness, Droid, Jan Agent |
The gateway preserves provider-native API dialects. It does not convert a Chat Completions model into a Responses or Messages model. Images, tool calling, reasoning and context length require compatible models too.
Ordinary Claude Code launch requires a server-enabled native Claude route. Cowork discovers eligible Claude models in the app and rejects CLI --model; an empty picker needs an eligible server catalog and working authentication. See the Cowork guide.
Credit, budgets and output-bound errors
- 402 or reservation refusal: review the credential's payer organization and available credit. A requested reservation can exceed available credit even when the wallet is not empty.
- Usage-limit refusal: inspect the applicable organization, team, user or platform budget. A usage budget is separate from wallet credit.
- 422 mentioning output bounds: the pricing guard cannot bound the selected request/model. Inspect the client's supported output-token setting and ask your administrator to check model output metadata. Do not disable the guard to make a request pass.
Read the actual response. Some clients return a zero exit status after a failed API request. See Credits and billing and Budgets and limits.
Desktop app still shows the old setup
Fully quit and reopen the app after configuration changes. Tokamak does not terminate active tasks. Start a new task or explicitly select the intended model if an existing conversation retains its old choice.
To undo managed desktop settings:
tokamak launch codex-app --restore
tokamak launch claude-cowork --restoreRestore works offline and refuses conflicting user edits. Keep backups private and reconcile settings manually if necessary. Droid and Oh My Pi have file backups, not these desktop restore commands; follow their specific guides.
Missing agent activity or unexpected usage
Server-recorded inference is the usage authority. Optional client logs, metrics and traces are separate activity and never an extra token charge. Not every client has an exporter. Missing telemetry does not prove zero tool use; unknown attribution stays in request totals.
Review Analytics and its Tools view with the correct account, organization and period. Explicit client provider choices, independently authenticated plugins and Claude's --native mode can route outside Tokamak. Client cost estimates are not wallet debits.
When asking for help
Include the Tokamak and client versions, operating system, deployment hostname, selected model, redacted command and exact error. State whether the failure occurred during configuration, startup, model discovery or a request. Remove API keys, private configuration, restore journals and prompt content before sharing diagnostics.