Errors

Every ASTra error has a stable code, a message that says what went wrong, and a remedy that says what to do next. An AI agent can read the remedy and recover without help.

What an error looks like

Through the MCP server, errors are returned as JSON:

example (shortened)

{
  "ok": false,
  "code": "E_VALIDATION",
  "message": "Node DOESNOTEXIST not found in AST.",
  "remedy": "Re-inspect ids via inspect (or search to locate text) and retry.",
  "isError": true
}

On the command line, the same information is printed as astra: error: [CODE] message. Remedy: ... and the exit code is 1 (the operation failed) or 2 (the command was used incorrectly).

Error codes

Code	What it means	What to do
`E_VALIDATION`	A batch or parameter was invalid, a node ID was not found, or saving would produce a document that fails the Word schema. The message says which, and nothing was written.	Read the remedy. Re-run inspect or search to get current node IDs, correct the operation, and try again.
`E_SANDBOX`	The path is outside the folders you allowed with --allowed-dir (including through a symbolic link).	Move the document into an allowed folder, or start the server with the right --allowed-dir.
`E_SESSION`	The session ID is unknown or has expired.	Call open_document again to start a new session.
`E_CONFLICT`	The target file already exists, or you asked to revert while the session has unsaved edits.	Pass force: true to overwrite, or discardUnsaved: true to discard unsaved edits. Edits that cancel out still count as unsaved.
`E_DEPENDENCY`	A tool ASTra needs is missing, usually LibreOffice for PDF export or page images.	Install LibreOffice and make sure it is on your PATH.
`E_QUOTA`	A batch is larger than the limit, or a document's history has reached its size or revision limit.	Split the batch into smaller batches.
`E_IO`	A file could not be read or written, or the history folder is not a normal one.	Check permissions and free disk space.
`E_NOT_FOUND`	The thing you asked for does not exist, for example reverting further back than the recorded history goes.	Check the history with astra history, then retry with a smaller --steps.

When an error says Nothing was written, you can safely retry: the file is exactly as it was before the failed call.