Exit codes

Exit codes of every urna command: the typed codes of doctor, setup and build, the engine and agent verbs, the explorer, the installers and the wheel's command.

Most urna verbs follow one convention: 0 on success, 1 on any error, 2 on a usage error. Three verbs have typed codes that scripts can branch on: urna doctor, urna setup and urna build. This page lists them all.

The convention

Code	Meaning
`0`	success
`1`	the command failed; the reason is printed on stderr as `Error: <message>`
`2`	usage error: unknown flag, missing argument, conflicting flags. Printed by the argument parser, with a usage line

$ urna validate /nonexistent.urna
Error: No such file or directory (os error 2)
$ echo $?
1
$ urna ask --bogus
error: unexpected argument '--bogus' found
$ echo $?
2

Engine verbs

inspect, validate, stats, media, search, search-ann, search-graph, search-space, search-text, benchmark, cite.

Code	Meaning
`0`	success
`1`	any error: file missing or unreadable, a failed integrity check, a dimension mismatch, a citation that does not belong to the file, a `model_hash` mismatch or an embedder failure (`search-text`)
`2`	usage error

urna validate has no separate code per failure: every integrity failure exits 1 with the reason on stderr. The error types are in typed errors.

urna doctor

Code	Meaning
`0`	every check passed (a scalar SIMD warning still exits `0`)
`2`	the Python interpreter is missing or does not run
`3`	`numpy` or `tokenizers` is missing
`4`	the potion embedder script was not found
`5`	the potion table is missing or is a git-lfs pointer
`6`	the embedder ran but failed or printed JSON that breaks the contract

The code is the first failing check's, in the order above: an interpreter without numpy exits 3 even if the embedder is missing too. Details in urna doctor.

urna setup

Code	Meaning
`0`	every planned step succeeded and verify passed; also a successful `--uninstall`
`2` to `6`	the steps succeeded, then verify failed with this doctor code
`10`	download failed (the `.sha256` or the payload)
`11`	the payload does not match the release checksum; nothing was installed
`12`	unpack failed (install root, archive, an escaping entry, missing embedder script, swap)
`13`	building the Python env failed
`14`	a step that should run is blocked (no `curl`, no data dir, no `uv` and no base Python, `URNA_PYTHON` without the packages)
`130`	cancelled in interactive mode
`1`	an error outside the steps (terminal setup, `--uninstall` failure)
`2`	also a usage error, such as `--uninstall --force`

The first non-zero code wins. Setup's own codes start at 10 so they never collide with the doctor codes. Details in urna setup.

urna build

urna build launches the forge (python/tools/urna_forge.py) and exits with the forge's code.

Code	Meaning
`0`	the build succeeded; also a successful `--dry-run`, even when a model's dependencies are missing
`1`	any other failure, with a Python traceback: a forge error, an encoder or tool failure, an SQLite error, a rejection from `urna.build`, a type error in the spec. From the launcher itself: `urna_forge.py` not found, the interpreter could not start, or the forge was killed by a signal
`2`	spec error (`spec error: <message>` on stderr), or a usage error from either the launcher or the forge. `urna build --strict-env` is a usage error: the flag exists only on `urna_forge.py`
`4`	registry error (`registry error: <message>`): unknown preset, `fake-test` without `URNA_ENABLE_FAKE_PRESET=1`, missing model dependencies, a pinned file mismatch, a worker failure

On an installed binary urna build always exits 1 with "urna_forge.py not found": the forge ships only in a repo checkout. See urna build.

urna ask and urna retrieve

Code	Meaning
`0`	success, including no hits (`ask` prints `no hits.`)
`1`	any error: file, embedder script not found, embedder failed, `model_hash` or dimension mismatch against the manifest
`2`	usage error

The query embedder is a Python script with its own exit codes, but the CLI does not pass them through: any non-zero exit becomes Error: embedder failed (status=...): <embedder stderr> and exit 1. The embedder's code is visible in that message:

Embedder	Its codes
`embed_query_potion.py` (potion corpora)	`0` ok, `2` no query, `3` table missing; missing `numpy` or `tokenizers` is a traceback with `1`
`embed_query_model.py` (registry-model corpora, checkout only)	`0` ok, `2` usage, `3` model files missing, `4` dependencies, unknown preset, or the remote-code or heavy-model gate
`python/embed_query.py` (`search-text`, checkout only)	`0` ok, `2` no query or usage; other failures (such as a model not cached while offline) are a traceback with `1`

The protocol is in query embedder protocol.

urna tui and a bare urna

Code	Meaning
`0`	you quit the explorer
`1`	the terminal could not be initialized, or another error
`2`	a bare `urna` without a terminal on both stdin and stdout: it prints the help and exits `2`, as for a missing subcommand; also a usage error

The installers

Script	Success	Failure
`install.sh`	`0`: installed, `--uninstall` done, or `--help`	`1` on any error: a missing tool (`curl`, `tar`, a SHA-256 tool), an unsupported OS or CPU, a failed download, a checksum mismatch, an unknown flag. Messages start with `urna-install: error:`
`install.ps1`	`0`: installed or `-Uninstall` done	`exit 1` on an unsupported architecture or a checksum mismatch; any other failed step stops the script with a PowerShell error

The wheel's urna command

The Python console script from the pip wheel is a different program from the binary:

Code	Meaning
`0`	success
`1`	any error, printed as `urna: error: <message>`
`2`	usage error, including any verb the wheel does not have (such as `urna ask`)

See the wheel's urna command.

Exit codes

The conventionCopy Anchor Link

Engine verbsCopy Anchor Link

urna doctorCopy Anchor Link

urna setupCopy Anchor Link

urna buildCopy Anchor Link

urna ask and urna retrieveCopy Anchor Link

urna tui and a bare urnaCopy Anchor Link

The installersCopy Anchor Link

The wheel's urna commandCopy Anchor Link

On this page