Exit codes

Generated from crates/versionx-core/src/error.rs (CoreError enum). Run cargo xtask docs --only exit-codes after changing error variants.

Stable top-level codes

Code	Meaning
0	Success.
1	Generic user error. Message on stderr describes it.
2	Config error. versionx.toml is missing, unparseable, or fails validation.
3	Policy violation. Rerun with --explain for specifics.
4	Network or I/O error. Check VERSIONX_LOG=debug.
5	Prerequisite mismatch during apply. Regenerate the plan.
6	Git error.
7	Daemon unavailable and --no-daemon was not set.
8	Waiver expired.
9	Saga failure. versionx saga status for recovery.
10+	Subsystem-specific — see the CoreError variants below.

CoreError variants

Variant	Message template	Description
NoConfig { path: String }	no versionx.toml found at \{path\} (hint: run versionx init first)	The user tried to run a mutating command without a config present and without opting into zero-config detection.
ConfigAlreadyExists { path: String }	versionx.toml already exists at \{path\} (pass --force to overwrite)	A versionx.toml already exists and --force was not passed.
NoEcosystemsDetected { path: String }	no ecosystems detected at \{path\}. Create a package.json, Cargo.toml, pyproject.toml, or .tool-versions file first, or run versionx init --template <kind>.	No ecosystem signals detected — nothing to synthesize.
UnknownRuntime (String)	no installer for runtime {0}(trynode, python, rust)	User asked for a runtime we don't have an installer for.
RuntimeNotPinned { tool: String }	no pinned version for {tool}— set[runtimes] {tool} = "..." in versionx.toml	User didn't pin a runtime this command needs.
Config (versionx_config :: ConfigError)	&lt;delegated&gt;	Underlying config load/parse failure.
Installer (versionx_runtime_trait :: InstallerError)	&lt;delegated&gt;	Underlying runtime install failure.
Adapter (versionx_adapter_trait :: AdapterError)	&lt;delegated&gt;	Underlying adapter failure.
State (versionx_state :: StateError)	&lt;delegated&gt;	State DB failure.
Lockfile (versionx_lockfile :: LockfileError)	&lt;delegated&gt;	Lockfile failure.
Paths (crate :: paths :: PathDetectionError)	&lt;delegated&gt;	Path resolution failure.
Io { path: String, source: std :: io :: Error }	i/o error at \{path\}: \{source\}	I/O failure with path context.
Serialize (String)	failed to serialize versionx.toml: \{0\}	Serialization failure writing back the config (toml_edit).

In scripts

versionx release plan > plan.json
rc=$?
if [ "$rc" -eq 3 ]; then
    echo "Policy violation. See above."
    exit 1
fi

See also

• Environment variables — turn on VERSIONX_LOG=debug when diagnosing.
• Debugging & tracing — for contributors adding new error variants.