Docs/Reference/Troubleshooting
Reference

Troubleshooting

4 min read

The problems people actually hit, with the fix for each. If yours is not here, the issue tracker is read daily.

Install and first run

  • Windows SmartScreen shows a prompt on the installer. The installer is code-signed; SmartScreen reputation for a fresh release build can lag a few days behind the signature. Check the publisher on the prompt, then More info - Run anyway. A hard block (no run option) is not expected - report it.
  • An agent will not start: command not found. DevThrottle runs the agents you have installed - it does not install Claude Code, Codex, or the others for you today. Install the agent's CLI, confirm it runs in a plain terminal, then start the session again.

Board and sessions

  • A session shows Working but nothing is happening. Open the card - the terminal is always the ground truth. If the agent is genuinely stuck, Interrupt it and re-prompt; status detection is tuned per agent but the terminal never lies.
  • Agents died when the machine rebooted. Sessions run on the machine; a reboot ends them. What you get back is the board, the history, and recovery behavior - re-start the sessions from their cards.

Phone and Cockpit

  • The phone cannot reach the Gateway. Reachability is the usual cause: the phone must be able to reach the Gateway machine (same Wi-Fi, or your VPN / overlay network from outside). Confirm the Cockpit opens from a browser on the same network first, then re-try the phone. See pairing.
  • A device was revoked by mistake. Revocation is not reversible in place - re-approve the device through the normal activation flow and it returns as a fresh row in Devices.

Voice and credits

  • Dictation gets technical words wrong. That is what the custom dictionary is for - add the term once and every device picks it up.
  • Hosted voice stopped working / API returns 402. Credits ran out. Top up on Billing (or enable automatic top-up with a monthly limit) and it resumes immediately.
Tip
The Director's status rail (bottom of the sidebar) is the first diagnostic: it shows Gateway, account, tools, and Control API health at a glance.
Note
When you report an issue, say which agent CLI, what the status rail showed, and what the terminal showed - those three answer most tickets in one round trip.