Error reference
Opens the app with a prompt to read this page.
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.