error codes

Error & Warning Codes — Frozen Contract

Machine-readable codes appear in three places of the --json envelope:

• error.code — process/business failures ({"success":false,"error":{"error":"...","code":"..."}})
• warnings[].code — advisory warnings on otherwise-successful commands
• data.results[].code — (batch, since v1.1.0) per-item failure code alongside results[].error. Same closed list as error.code, with one difference: an unclassifiable item failure leaves code absent (no internal_error bucket at item level) — treat a missing code as unclassified and fall back to the error message text.

Contract: codes are FROZEN, message text is not. Programmatic callers must branch on code (and error.suggestion / structured fields where present), never on message wording — messages may be reworded or localized in any release. Existing codes are never renamed or removed; new codes may be added (consumers should treat unknown codes as a generic member of their family). All codes are lowercase snake_case.

Errors that cannot be classified carry internal_error — a catch-all whose presence in logs is a signal to file an issue so the path gets a real code.

Not-found family

Code	Meaning
not_found	Addressed element does not exist (index out of range, name unknown, sheet missing)
path_not_found	DOM path could not be walked
file_not_found	Document file does not exist
range_target_not_found	range= character offset does not resolve inside the run
dump_reader_not_found / exporter_not_found / plugin_not_found	Named tooling component is not installed
zero_matches	(warning) a find= pattern matched nothing — the command itself succeeded

Invalid-input family

Code	Meaning
invalid_value	Property value fails validation (wrong type, out of grammar)
invalid_selector	Malformed CSS-style/filter selector
invalid_path / unsupported_path	Path syntactically invalid / not addressable by this command
invalid_argument / missing_argument / invalid_input	CLI argument errors
invalid_json / corrupt_batch	Batch/JSON payload cannot be parsed
invalid_format / invalid_type / invalid_issue_type / invalid_xpath / invalid_render	Enumerated-option value not recognized
invalid_number_format	(warning) Excel number format Excel itself may reject (0x800A03EC)
missing_property	Mutation invoked with nothing to apply
missing_prop_flag	Bare key=value given without --prop
bare_selector_rejected	Unscoped selector would mutate document-wide; scope it
out_of_range / max_depth_exceeded	Numeric/recursion limits exceeded
merge_not_exact	Cell merge range does not exactly cover target

Unsupported family

Code	Meaning
unsupported_property	Property key not supported on this element (exit 2 when partially applied)
unsupported_element / unsupported_type	Element type not supported by add/dump
unsupported_command / unsupported_format / unsupported_plugin_kind	Verb/format/plugin class not supported
unrecognized_latex_command	(warning) equation written with a literal-text fallback

Document-state family

Code	Meaning
document_protected	Write blocked by document protection (--force to override)
flush_policy_conflict	Atomic batch on a dirty FLUSH=off resident session — save first or use --best-effort
corrupt_file / invalid_document	Package/XML is damaged
file_exists / file_locked / file_required / io_error	Filesystem-level failures
duplicate_name	Name collision (sheet, style, …)
decompression_bomb	Package expansion exceeds safety limits
broken_chart_relationship	Chart part references a missing relationship
validation_error	(warning/verdict) schema validation found errors
text_overflow / position_overlap	(warnings) content exceeds shape bounds / shapes overlap

Process / infrastructure family

Code	Meaning
internal_error	Unclassified failure (catch-all)
protocol_mismatch	Resident/CLI version skew
output_too_large	Result spilled to a temp file (pointer returned)
native_unavailable / no_screenshot_backend / page_count_unavailable / refresh_failed	Optional native capability missing
plugin_command_failed / plugin_contract_violation / plugin_create_failed / plugin_failed / plugin_idle_timeout / plugin_spawn_failed / plugin_stream_closed	Plugin runtime failures
lint_fixture_missing	Lint fixture absent
advisory / warning / filter_warning / auto_corrected	Generic advisory warnings (auto_corrected: a distance-1 prop typo was fixed and applied)

Category mapping for common agent routing

Agent-side intent	officecli codes
"target doesn't exist"	not_found, path_not_found, file_not_found, zero_matches
"property not supported"	unsupported_property, unsupported_element, unsupported_type
"bad path syntax"	invalid_path, unsupported_path, invalid_xpath
"malformed filter/selector"	invalid_selector, bare_selector_rejected
"bad value"	invalid_value, invalid_number_format, out_of_range

Exit codes: 0 success · 1 failure (mirrors envelope.success) · 2 applied-with-caveats (unsupported_property / unrecognized_latex_command).