Troubleshooting
Most problems show up as a notice: a message that names what stopped and why. This page covers the ones people meet most.
Installing and starting
Section titled “Installing and starting”Windows says the installer is from an unknown publisher. The builds are not code-signed yet. Choose More info, then Run anyway.
The macOS app does not update itself. Unsigned macOS apps cannot. Download the new version from the releases page and install it over the old one.
The app says its port is taken. Something else is listening where the app’s local process wants to start, often an old copy that did not quit. The panel names the process and offers to End that process, or to Use another port this time for this session only.
The app shows a start-up failure. Its local process crashed or did not answer within a minute. The panel shows the last lines it printed. Press Retry; if it fails again, report the bug with those lines.
I closed the window and the app is still running. That is on purpose, so loops keep going. Quit from the tray menu.
A loop stopped
Section titled “A loop stopped”A loop that stops says why. The usual reasons:
| Notice | What to do |
|---|---|
| The loop reached its max executions, or its error caps | Read the Run Log to see which bubble kept failing. Fix the cause, or raise the cap in the loop’s settings, then press Play. |
| There is nothing to do: cards are waiting in Draft | Approve the cards you want worked, then press Play. |
| Cards are waiting on each other | Two or more cards depend on each other. Edit one so the chain can start. |
| Rate limited | The loop resumes by itself if the provider said how long to wait. Otherwise press Play later, or use a pool. |
| Provider down | The provider did not answer after three tries. Press Play when it is back. |
| The board’s pass budget is used up | Every loop’s max executions, added together, is the board’s budget. Raise the max on the loop you want to go further. |
After you fix a halt, Play clears the loop’s error counts and starts it again.
A pass ended in ERROR
Section titled “A pass ended in ERROR”ERROR means the agent never really ran. Common causes:
- The key belongs to another provider. A bubble points at a key saved for a different provider. Pick the right key in the bubble’s inspector.
- The model cannot do the job. Some small models cannot call tools or hold the reply’s shape. Choose a larger model for that bubble.
- An image, and no one to see it. The bubble’s model cannot see images and no vision model is set. Set one on the Models page under Helper models.
Commands and tools
Section titled “Commands and tools”“Sandbox unavailable”. The sandbox is on but its backend is not ready. Settings, Command sandbox, shows the one step to fix it and the exact command to copy. Commands stay refused until then; they never run unsandboxed.
“Shell missing” on Windows. Agents need Git for Windows to run command chains and redirects. Install it, then restart the app.
A command waits for an answer that never comes. Approvals appear in the app’s window. If no window is open, the command is refused instead of waiting.
“Browser missing”. The visual review and the browser tools need Chrome, Edge or a downloaded Chromium. Settings, Agent browser, offers the download.
Web search says it is down. The built-in search did not answer, so results came from npm, GitHub, Stack Overflow, MDN and Wikipedia only. It restarts on the next search. Adding a Brave or Tavily key gives a second route.
The preview
Section titled “The preview”The preview will not start.
Previews need a dev or start script in the project’s package.json (or in one first-level folder).
A board that sandboxes commands cannot run one. If it crashed, the Report tab shows the exit code and
the last lines of its log.
No finish report after a run. Only runs that ran out of work on their own hand over. A run you paused or stopped, or one that hit a cap, does not write a report.