#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. 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. |