# Error codes A refusal looks like `{"ok": false, "error": {"code": "...", "message": "...", "details": ...}}` with exit code 2. Exit code 1 (`internal`) is an unexpected failure. `message` is written for people in the app's language; `code` never changes with the language, so decide on `code`. | Code | What it means | What to do | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invalid_argument` | A command option or file is wrong: unknown option, missing value, unreadable `--edit` file, a bad `--from`/`--to`, an output this project cannot export, an image added before the project has a track document, a sound added before the project has an audio track, or a local `transcribe` without a video language (`details.languages` lists the choices). | Fix the command using `message`. For images, apply a track edit (for example add a track) first. For sounds (`asset add` of audio, `sfx use`), add an audio track first. For `transcribe`, ask the person which language the video is in and pass `--language`. | | `project_not_found` | The path is not a CutZal project: the video was never opened in CutZal, the path is a folder, or the project moved. | Ask the person to open the video in CutZal once, then pass the video path or its `edit/cutzal.json`. | | `connection_disabled` | CutZal has this project open but its external connection is off, so the command may not touch the files. With `details.reason: "socket_blocked"` the connection is on, but the command was not allowed to reach it (usually your sandbox). | Ask the person to turn on the external agent connection in CutZal Settings > Agent, or to close the project. Then retry. For `socket_blocked`, run `cutzal` outside the sandbox (Claude Code: add `"cutzal *"` to `sandbox.excludedCommands`). | | `ambiguous_owner` | More than one CutZal app has this project open. `details.pids` lists them. | Ask the person to close the extra app. | | `version_mismatch` | The `cutzal` command and the running CutZal are different versions. | Ask the person to update CutZal, or to reinstall the command from CutZal Settings > Agent so it matches the running app. | | `stale_revision` | The project changed. `details` includes `currentRevision`, up to 50 `changes`, and completeness fields. | Preserve `human`/`phone` edits, especially restored ranges. Read `changes --since`, then current `context`/`transcript` if history or ranges are incomplete. Replan before retrying; do not replay the old edit with a new revision. | | `locked` | Another task has control, or the person has taken over (`details.reason: "human_control"`). `session_required` means the active session ID is required. | Do not bypass the lock. For your held session, poll `session status` every 15 seconds and preserve handback edits before resuming. | | `session_ended` | The session ended or this app does not know it. `details.reason` is `human`, `idle`, `app_exit` or `unknown`. | Read current context and declare a fresh session. Never reuse an old ID to retry writes. | | `id_conflict` | This `--id` was already used for a different edit. | Use a new `--id`. | | `invalid_edit` | The edit JSON has the wrong shape or breaks a rule (overlapping clips, locked track, wrong asset kind, bad range, or a layout edit for a range with no camera or only a full-picture camera). | Fix the edit using `message` and [edits.md](https://cutzal.ai/docs/en/agents/edits.md). `preview` until it is `ready`. | | `blocked` | The edit would change placed clips in a way the person should decide. Nothing was applied. The plan is in `details`. | Change the edit, or describe it to the person and let them do it in CutZal. | | `busy` | CutZal or another `cutzal` command is working on this project, the person has a dialog open, or the app did not answer in time. | Wait a few seconds and run the same command again. For `apply` and `rewind` keep the same `--id`: if the earlier try did get applied, you get `duplicate` instead of a second change. The other commands take no `--id`. | | `app_required` | This needs the open app and the person: `export`, a `rewind` that would undo the person's own edits, or a `transcribe` that would cost money (`--engine elevenlabs`) or needs the local model downloaded first. | Ask the person to open the project in CutZal and turn on the external connection, then retry. For `transcribe`, ask the person to start the ElevenLabs transcription or download the local model in CutZal. | | `declined` | The person said no in CutZal (closed the window or pressed decline). | Do not retry the same request unless the person asks. | | `confirmation_timeout` | Nobody confirmed in CutZal within 10 minutes. | Ask the person before trying again. | | `cancelled` | The person cancelled the export in CutZal. | Ask the person what they want. | | `unsupported` | This project cannot do that: for example `transcript` before transcription or `capture` on an old layout project. For `context`, the app may lack screen-state support. | Follow the message. Update CutZal for screen-state support; never bypass its ownership with headless. For an untranscribed project, use `cutzal transcribe` (free, local); the person starts paid ElevenLabs transcription in CutZal. | | `internal` | An unexpected failure (exit code 1). A message with `EPERM` or `EACCES` on `~/.cutzal` or the project folder usually means a sandbox blocked the write. | Tell the person the `message`. Do not retry in a loop. For a blocked write, run `cutzal` outside the sandbox. |