# Agent errors and fixes | User Guide | Shotomatic

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

- Type: Public web page
- Canonical page: [https://www.shotomatic.com/guide/ai-agents/errors](https://www.shotomatic.com/guide/ai-agents/errors)
- Markdown page: [https://www.shotomatic.com/guide/ai-agents/errors.md](https://www.shotomatic.com/guide/ai-agents/errors.md)

Browse the user guide

On this page

1.  [Error codes](#error-codes)
2.  [Why a capture paused](#why-a-capture-paused)
3.  [Why a capture ended](#why-a-capture-ended)

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

Code

What it means

What you can do

`approval_required`

The agent has not been allowed yet. Until then it can only read status.

Open Shotomatic and select **Allow** on the approval card.

`permission_required`

macOS has not granted **Screen Recording**, or **Accessibility** for key presses.

Turn Shotomatic on in **System Settings > Privacy & Security**, then reopen Shotomatic. See [macOS permissions](https://www.shotomatic.com/guide/get-started/macos-permissions).

`license_limit`

A free-plan limit was reached, such as screenshots per day or URLs per batch.

Use a smaller job, wait until tomorrow, or see [Pricing](https://www.shotomatic.com/pricing). Screenshots already saved are kept.

`pro_feature`

The request uses a feature that needs Pro, for the agent as for you.

Ask for the job without that feature, or upgrade.

`busy`

Another 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_unavailable`

The window or screen is gone or cannot be captured.

Open the window again, or ask the agent to pick another source.

`not_found`

The session, Document, Workflow, or job id does not exist anymore.

Ask the agent to list items again.

`revision_conflict`

The 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_installed`

Website Capture needs Shotomatic's browser, which is not installed yet.

Open the Website Capture page in Shotomatic and install the browser.

`invalid_request`

The agent sent a value Shotomatic cannot use.

Usually the agent fixes this itself. If it repeats, rephrase the request.

`confirmation_declined`

You selected **Cancel** on a confirmation card.

Nothing. Nothing was deleted or scheduled.

`confirmation_timeout`

Nobody answered a confirmation card within a minute.

Ask again when you are at the computer.

`unavailable`

Shotomatic's main window is not open, or the app could not start the job.

Open Shotomatic, keep its main window open, and ask again.

`failed`

Something else went wrong.

Check the message, try again, and [contact support](mailto:support@shotomatic.com) 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](https://www.shotomatic.com/guide/troubleshooting/common-issues#an-ai-agent-cannot-connect-or-use-shotomatic) or [the client troubleshooting list](https://www.shotomatic.com/guide/ai-agents/other-agents#troubleshooting).

## On this page

1.  [Error codes](#error-codes)
2.  [Why a capture paused](#why-a-capture-paused)
3.  [Why a capture ended](#why-a-capture-ended)

## About this version

This Markdown page is generated from the server-rendered public page on Shotomatic. Interactive controls and site navigation are omitted. Use the canonical page when citing or sharing it with people.
