Browse the user guide

Agent errors and fixes

Error codes and stop reasons an AI agent can get from Shotomatic, what each one means, and what you can do about it.

Updated November 16, 2026

View Markdown
On this page

When a Shotomatic tool cannot do what an agent asked, it returns an error with a code, a message, whether a retry can work, and often a step for you. A good agent passes that step on to you. This page lists every code so you know what to do when an agent reports one.

Error codes

CodeWhat it meansWhat you can do
approval_requiredThe agent has not been allowed yet. Until then it can only read status.Open Shotomatic and select Allow on the approval card.
permission_requiredmacOS has not granted Screen Recording, or Accessibility for key presses.Turn Shotomatic on in System Settings > Privacy & Security, then reopen Shotomatic. See macOS permissions.
license_limitA free-plan limit was reached, such as screenshots per day or URLs per batch.Use a smaller job, wait until tomorrow, or see Pricing. Screenshots already saved are kept.
pro_featureThe request uses a feature that needs Pro, for the agent as for you.Ask for the job without that feature, or upgrade.
busyAnother capture is running, or Shotomatic is already asking you something.Let the other job finish or stop it, answer the open card, then ask again.
source_unavailableThe window or screen is gone or cannot be captured.Open the window again, or ask the agent to pick another source.
not_foundThe session, Document, Workflow, or job id does not exist anymore.Ask the agent to list items again.
revision_conflictThe Document changed after the agent read it, usually because you edited it.The agent should read the Document again and reapply its change.
browser_not_installedWebsite Capture needs Shotomatic's browser, which is not installed yet.Open the Website Capture page in Shotomatic and install the browser.
invalid_requestThe agent sent a value Shotomatic cannot use.Usually the agent fixes this itself. If it repeats, rephrase the request.
confirmation_declinedYou selected Cancel on a confirmation card.Nothing. Nothing was deleted or scheduled.
confirmation_timeoutNobody answered a confirmation card within a minute.Ask again when you are at the computer.
unavailableShotomatic's main window is not open, or the app could not start the job.Open Shotomatic, keep its main window open, and ask again.
failedSomething else went wrong.Check the message, try again, and contact support if it repeats.

Why a capture paused

An Auto Capture an agent started pauses instead of pressing keys in the wrong place:

  • Another window is in front. Shotomatic never presses a key while the captured window is not in front. Bring it back and tell the agent to resume. Keep your hands off the computer during the capture.
  • The screen is locked. Unlock it and tell the agent to resume.

Why a capture ended

When a job ends, the agent sees a reason. These are normal:

  • Content stopped changing. With a key press, Shotomatic stops when the page no longer changes, for example at the end of a book.
  • Stop condition reached. The number of screenshots, the duration, or the end time you asked for was reached.
  • Stopped by you or by the agent. You selected Finish capture, or the agent stopped the job. Screenshots already taken are kept.

These mean something needs attention:

  • Free limit reached. The free plan's limit ended the capture. The screenshots saved so far are in Capture History. For Action Capture, the free plan ends a capture after 5 steps.
  • Window closed. The captured window was closed during the capture.
  • Window could not stay in front. Shotomatic could not bring the window to the front. Keep it visible, do not use the computer, and ask the agent to start again.
  • Session ended elsewhere. The Capture Session was closed in Shotomatic while the capture ran.

Still stuck? See Troubleshooting or the client troubleshooting list.

Agent errors and fixes | User Guide | Shotomatic