# Error reference

> Every refusal code stetdoc returns, its exit status, what it means and what to do next.

Source: https://stetdoc.clauseo.chat/docs/reference/errors · stetdoc 0.9.1

Every failure is a `StetError`: a stable code, a one-line message, a `next` hint and,
for batches, the index of the failing operation. The CLI, `--json` output and the
library all use these codes. From 1.0, codes and their exit classes are frozen. New
codes may be added, and existing codes are never repurposed or removed outside a major
version.

## Exit classes

Exit status 0 is success. CLI argument errors also exit with 2. They belong to the CLI and are not codes.

| Exit | Class | Codes |
|---|---|---|
| 1 | operation failed | `unsupported`, `cross_block`, `readonly_region`, `scope_violation`, `io_error` |
| 2 | usage | `invalid_payload` |
| 3 | target | `not_found`, `ambiguous_match`, `count_mismatch` |
| 4 | stale | `stale_ref`, `stale_files`, `pending_edits`, `stale_target` |
| 5 | validation | `validation_failed` |
| 6 | input | `malformed_input`, `limit_exceeded`, `corrupt_complement`, `unsupported_version` |
| 7 | internal | `internal` |

## Codes

### `unsupported`

Exit 1 (operation failed). The request is well formed but asks for something this release does not do, such as reordering refs in a readable file or creating a file in the editor.

**Next:** Use a supported operation (the capabilities list names them), or leave this content untouched.

### `cross_block`

Exit 1 (operation failed). A text range or find match spans more than one block. Operations address one block at a time.

**Next:** Split the edit into one operation per block, or merge the blocks first.

### `readonly_region`

Exit 1 (operation failed). The edit changes read-only content: a clause number, a field result, a placeholder or someone else's deletion.

**Next:** Edit the surrounding text instead and leave the read-only region as it is.

### `scope_violation`

Exit 1 (operation failed). The batch would change a block outside the refs named by the scope guard. Nothing was applied.

**Next:** Add the block's ref to the scope, or remove the operation that reaches outside it.

### `io_error`

Exit 1 (operation failed). The file system refused a read or a write that the request needs: a folder that is not writable, a full disk, or a working copy that another process holds. Only surfaces that do file I/O raise it; the core never does.

**Next:** Fix the cause the message names (permissions, space, another process), then run the same command again.

### `invalid_payload`

Exit 2 (usage). An operation batch or readable file could not be parsed or is internally inconsistent: an unknown operation, a missing field, a bad value or a duplicated ref.

**Next:** Fix the payload and retry. The capabilities list names the valid operations and their fields.

### `not_found`

Exit 3 (target). A ref, revision id, comment id or find text matches nothing.

**Next:** View the document to list the current refs, then retry with one that exists.

### `ambiguous_match`

Exit 3 (target). A find text or string matches more than one place, so the target is not unique.

**Next:** Add surrounding text to make the match unique, or target one block by its ref.

### `count_mismatch`

Exit 3 (target). A find text matches a different number of times from the count the request expects, so nothing was applied.

**Next:** Look at the places listed, then give the count they show or a narrower scope.

### `stale_ref`

Exit 4 (stale). A ref names a block that was deleted, or belongs to a different ref namespace than the document, for example after reopening saved bytes.

**Next:** View the document again to get fresh refs, then rewrite the batch.

### `stale_files`

Exit 4 (stale). Readable files were rendered from an older state version, or from a different ref namespace, than the document now has.

**Next:** Export the working copy again to render fresh readable files, then redo the hand edits on them.

### `pending_edits`

Exit 4 (stale). The working copy has hand edits to readable files that have not been packed, so applying operations would lose or mix them.

**Next:** Apply the pending hand edits as a files edit, or discard them, then retry the operation.

### `stale_target`

Exit 4 (stale). The file a command would write holds a version that the command has not seen, so writing it could overwrite a newer version: a pack's output that is neither the document the working copy came from nor one it packed, or a .docx edited in place that someone wrote during the edit. Only surfaces that write files raise it.

**Next:** Read the file at that path again and redo the edits on what it holds now, or write to another path.

### `validation_failed`

Exit 5 (validation). The edit would add schema or Word-rule violations. Nothing was applied. Problems already present in the input are reported by check, not blocked.

**Next:** Change the edit so it does not add the violation the message describes, then retry. A check of the document lists problems that were already there.

### `malformed_input`

Exit 6 (input). The input is not a readable .docx package: a bad ZIP structure, missing required parts, or XML that does not parse.

**Next:** Check that the input is a valid .docx. Opening and re-saving it in Word or LibreOffice often repairs it.

### `limit_exceeded`

Exit 6 (input). The input or the request exceeds a configured limit, such as entry count, size, compression ratio, nesting depth or batch size.

**Next:** Use a smaller input, or raise the limit in the open options if the source is trusted.

### `corrupt_complement`

Exit 6 (input). The complement of a working copy failed verification: its content hashes, ref map or format did not match.

**Next:** Do not edit the complement. Restore the working copy, or start again from the original .docx.

### `unsupported_version`

Exit 6 (input). The complement was written by a newer major version of stetdoc, or in a format version this release cannot read.

**Next:** Upgrade stetdoc to a version that reads this complement.

### `internal`

Exit 7 (internal). A bug in stetdoc: an internal consistency check failed, so the request was refused and the document was not changed. The content of the request never causes this.

**Next:** Report this as a bug in stetdoc, with the input and the request that caused it. Do not try a different edit to get around it.