Troubleshooting

The problems you are most likely to meet, what causes each one, and what to do about it. Some of these are the app working as designed in a way that can look like a fault.

Providers and accounts

• A provider tab carries an exclamation mark. That command line tool is not on this machine. In Settings > AI Providers, its CLI row reads Not installed, names the install command, and has an Install button that runs it. Of these tools, terminal runs use Claude Code and Codex today. The Cursor and OpenCode tabs only manage those tools. See Providers.
• A run stops at once and asks whether the CLI is installed. The terminal could not start the provider’s command. Install it from the AI Providers tab, then send the prompt again.
• An account row reads Failed. The sign in did not finish, or it stopped working. Press Link account for that provider on the Accounts tab and sign in again. Signing in to the same account again updates its existing row instead of adding a second one.
• An account you linked is gone after a restart. The list of linked accounts is kept in a MongoDB database, named by db.json in the data folder. Without one, only the sign ins the command line tools already hold come back, because the app finds them again at every launch. Point db.json at a MongoDB database, or sign in with the tool itself so the app picks the sign in up. See The data folder.
• A Codex run fails with an API Error line. Codex runs the model the terminal’s picker shows. The line gives the status and the provider’s own sentence. One cause is an account whose plan does not offer that model. Pick another model or another account in the terminal’s model picker, then send again.

Runs

• A run stopped on a usage limit line. The provider ended the turn because the usage window is spent. The line carries Auto continue, which sends the last prompt again once the window resets. See Auto continue.
• A run stopped on a provider error. An overloaded service, a server error, a rate limit or a dropped stream counts as a passing error. The first one on a terminal goes on by itself after a minute, with the countdown beside the line. If the run that follows stops on such an error again, the line offers Auto continue instead, and choosing it sends after a ten second countdown.
• A run stopped on a line that starts Ceiling limit of this plan hit. The account has used more of a weekly or monthly window than the ceiling you set for it. Continue lets this terminal go on with that account until the window resets. To change the ceiling, use the box on the account’s card on the Accounts tab. See Stop loss and ceilings.
• A popup appeared before the prompt was sent. That is a cost warning about an action that throws the conversation’s cache away. Send anyway sends the prompt. Cancel ends the turn, and the terminal prints Cancelled. Each warning has its own switch in Settings > Harness. See Cost warnings.

Approvals

• A command was refused. The terminal shows the refused call and the reason. There are four causes.
  • An approval rule set to Deny matched it. The reason names the rule.
  • A rule set to Ask matched it, and nobody answered before the Ask timeout ran out. The default is 120 seconds.
  • Auto mode is off, so every command without a matching rule asks, and the ask timed out.
  • The command named a path outside the terminal’s own checkout. A terminal only works inside its checkout, whatever the rules say.
  Change the rules, the timeout and Auto mode in Settings > Terminal > Command approvals. See Approvals.

Builds

• A build row says there is no build script for this project. The first Build on a project runs a detection that writes the script, and that detection did not produce one. Press Build again, or choose Regenerate Script from the row menu.
• A build row says the detection timed out, produced no build spec, or described a different project. The model that reads the project did not give a usable answer. Press Build again, or choose Regenerate Script from the row menu.
• A build row says a required port could not be freed. Before it starts, Build frees the ports the project needs. It stops another build that holds one, and ends any other program listening on it. If a port is still taken after that, close the program holding it and press Build again.
• A build row says it was unable to resolve conflicts. A combined build merges the work of every terminal that is included in builds, and two of them changed the same lines in a way that could not be merged. Check the project folder for changes you have not committed, or leave one terminal out of builds.
• A build row says the server stopped, or the script ended before the server came up. The project’s own script failed. Choose Copy Log from the row menu to read what it printed.
• A build row says the project directory was not found. The folder was moved or deleted after it was opened. Open the folder as a project again once it is back.

More on the queue is on The build queue.

Git

• A pull, push, squash or unstash hits a conflict. The app hands the conflicted files to the fallback model before it gives up. The popup reads Resolving conflicts, then Conflicts resolved or Auto resolve failed. The fallback model is chosen in Settings > AI Providers.
• The model could not resolve the conflict. The pull, push or squash is undone, so nothing changes, and the popup names the conflicted files for you to fix in the editor. When your own uncommitted changes were the ones that conflicted, the files stay in the tree with their conflict markers, and git’s stash still holds your copy.

More on the popups is on Remote git and Auto git and worktrees.

The mobile remote

• Show code is greyed out. The desktop is not connected to the relay yet. Wait for Connected under the switch, then show the code.
• The phone says the code expired or was already used. A code works once, for two minutes. Show the code again on the desktop and scan the new one.
• The phone reads Desktop unreachable, retrying. The desktop is not dialing. Either the app is closed or the remote switch is off. On Windows the app quits with its last window, so closing the window ends the link. The phone reconnects by itself once the desktop is back.
• The phone went back to the scan screen. The phone was removed under Sessions on the desktop, or it did not connect for thirty days. The message on the scan screen says which. Show a new code and scan it.
• A project is on the desktop but not on the phone. It is unticked in Settings on the Mobile Remote tab. An unticked project does not reach the phone at all, including its terminals, its map, its git and its reviews. Tick it again and it comes back at once.
• A terminal disappeared while you were reading it. It was closed on the desktop. The phone goes back to the project pager on the next update.
• A run took no pictures. Pictures are only taken while the remote is on. Beyond that, the desktop only takes pictures of browser tests it serves, so a checkout without Playwright, or tests in Firefox or WebKit, produce none. A picture the run saved outside the folder named by WARSHALL_SCREENSHOTS_DIR is not picked up. See Pictures and files.
• A file will not open on the phone. Images and PDFs over about twenty megabytes are too large for the phone. Other kinds of file say to open them on the desktop, and a file deleted after the run read it says so.
• A review file stops part way. A file longer than 1500 lines is cut, and the diff says so. Open that file on the desktop.

Signing in to Warshall

• The code expired. A device code is good for ten minutes. Start the sign in again from the Warshall account card.
• The sign in was denied on the website. Deny was chosen on the device page. Start again and choose Approve.
• The account service is not reachable. The machine is offline, or the service is not answering. Nothing is signed in or out because of this. Try again.
• This device was signed out of the account. The saved session is checked once at every launch, and a revoked one signs the desktop out. Sign in again.

More on accounts is on Warshall account.