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 (the gateway) wants to start, often an old copy that did not quit. The panel names the process and offers to end it (End that gateway for an old Perfica, otherwise End followed by its name or its PID), or to Use another port this time for this session only.
The app says The gateway could not start. Its local process crashed or did not answer within a minute. The panel shows the last lines it printed. Press Try again; 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 with Quit Perfica in the tray menu.
A loop stopped
Section titled “A loop stopped”A loop that stops says why, in a notice and in its panel on the canvas. The usual reasons:
| What the app says | What to do |
|---|---|
| The loop reached its max executions, or its error caps | Read the Manager’s Log tab to see which bubble kept failing. Fix the cause, or raise the cap in the loop’s settings, then press Play. |
| There is no work left: 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. Open the Task Book and press Stop waiting on one of them. |
| The model’s quota ran out, with the time it tries again | Nothing: the loop starts again by itself at that time, and keeps trying for as long as the board is left alone. Press Play to try now, Add a paid key to carry on without waiting, or use a pool. |
| The model provider stopped answering | The provider did not answer even after Perfica asked again three times over about seven seconds. No error was counted. Check it is running, then press Play. |
| 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”“A command was refused because it could not be sandboxed”. The sandbox is on but its backend is not ready. Settings › Autonomy › Command sandbox shows the one step to fix it and the exact command to copy. Commands stay refused until then; they never run unsandboxed.
“Agents need Git for Windows to run command lines”. Agents need Git for Windows to run command chains and redirects. Install it. Nothing needs restarting: the next command looks for it again.
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.
“Agents need a browser to look at the running app”. The visual review and the browser tools need Chrome, Edge or a downloaded Chromium. Settings › Autonomy › Agent browser offers the download. Nothing needs restarting.
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. A Brave or Tavily key sends every search to that service instead of the built-in one.
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. To get one anyway, open the Manager’s Report tab and press Write report.