# Exit and error codes

> The process exit codes, and every AXX-Exxxx error code with what it means and how to fix it.

Source: https://axx.nimbusxr.us/references/error-codes/

Every user-facing error has a stable code. `axx explain AXX-E0102` prints an entry from this page; with `--json`, errors appear in `errors[]` with `code`, `message`, `location`, `hint` and `docs`.

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success: every selected scenario passed (or the command succeeded). |
| 1 | At least one scenario failed. |
| 2 | Usage or configuration error: bad flags, invalid `axx.yaml`, unparsable features. |
| 3 | Undefined or ambiguous steps, or lint violations. |
| 4 | Environment or lifecycle failure: an app did not start, become ready or stop. |
| 5 | Reserved (not used). |
| 130 | Interrupted (Ctrl-C); apps were stopped and cleaned up. |

## Command line

### AXX-E0001

**Invalid usage** · exit 2

The command line could not be parsed: an unknown command or flag, a missing flag value, or the wrong number of arguments.

**Fix:** Run the command with `--help` to see its flags and arguments.

### AXX-E0002

**Invalid -D property** · exit 2

A `-D` flag is not in `name=value` form.

**Fix:** Pass properties as `-D name=value` (repeat the flag for several properties).

### AXX-E0004

**Cannot start the run** · exit 2

The run options are inconsistent, for example an unknown `--order` value or a reporter whose output cannot be created.

**Fix:** Check the message for the offending option; `axx run --help` lists the valid values.

### AXX-E0005

**Missing output directory** · exit 2

`axx docs export` needs to know where to write.

**Fix:** Pass `--out <dir>`.

### AXX-E0007

**Invalid skills scope** · exit 2

`axx skills install --scope` accepts `project` (the repository) or `user` (your home directory).

**Fix:** Use `--scope project` or `--scope user`.

### AXX-E0009

**Unknown error code** · exit 2

`axx explain` was given a code that is not in the catalog.

**Fix:** Check the code; every code is listed on the error-codes reference page.

### AXX-E0010

**Unknown schema kind** · exit 2

`axx schema --kind` accepts config (axx.yaml) or one of the fixture spec kinds: factory, fixture, prototype.

**Fix:** Use `--kind config`, `--kind factory`, `--kind fixture` or `--kind prototype`.

### AXX-E0011

**Invalid pack argument** · exit 2

`axx pack` was given a pack that is not the name of one of Axx's packs, an existing local directory or a Go module path, or one that is not listed.

**Fix:** `axx pack list` lists Axx's packs; other packs are added by path (`./steps`, created with `axx pack new`) or Go module path (`github.com/team/axx-grpc@v1.2.0`).

## Configuration (axx.yaml)

### AXX-E0100

**Config file not found** · exit 2

The file given with `--config` does not exist or cannot be read.

**Fix:** Fix the path, or omit `--config` to let Axx search upward for `axx.yaml` (the file is optional).

### AXX-E0101

**Config is not valid YAML** · exit 2

`axx.yaml` (or a profile/local override) has a YAML syntax error; the message quotes the line.

**Fix:** Fix the indentation or quoting at the reported line. Values containing `: ` or starting with `{`, `[`, `*` or `&` need quotes.

### AXX-E0102

**Invalid configuration** · exit 2

`axx.yaml` does not match the schema: an unknown key, a wrong type or an invalid value. Each problem is reported with its line.

**Fix:** Add `# yaml-language-server: $schema=https://axx.nimbusxr.us/schemas/v0/axx.schema.json` to get completion in your editor, or run `axx schema` to read the schema.

### AXX-E0104

**Unknown profile** · exit 2

`--profile` (or `AXX_PROFILE`) names a profile that is not defined under `profiles:` in `axx.yaml`.

**Fix:** Define the profile or pick one of the listed names.

## Feature files and filters

### AXX-E0200

**Feature file does not parse** · exit 2

A `.feature` file has a Gherkin syntax error.

**Fix:** Fix the reported line. `axx validate` checks every feature without running anything.

### AXX-E0201

**Feature path not found** · exit 2

A path given on the command line or in `run.paths` does not exist.

**Fix:** Check the path. Paths on the command line resolve from the working directory; `run.paths` resolve from the directory of `axx.yaml`.

### AXX-E0202

**Invalid tag expression** · exit 2

`--tags` (or `run.tags`) is not a valid Cucumber tag expression.

**Fix:** Use tags with `and`, `or`, `not` and parentheses, e.g. `--tags '@smoke and not @slow'`.

### AXX-E0203

**Invalid name filter** · exit 2

A `--name` pattern is not a valid regular expression.

**Fix:** Escape special characters, or pass a plain substring.

## Packs, steps and resources

### AXX-E0300

**Pack cannot be loaded** · exit 2

A step pack failed to load or initialize: a step expression that does not compile, a duplicate parameter type, or pack configuration under `packs:` that is invalid.

**Fix:** Read the wrapped message. For a pack of your own, fix its step definitions; for Axx's packs, check `packs.<name>` in `axx.yaml`.

### AXX-E0301

**Resource not found** · exit 2

A file referenced by a step (seed, payload, schema, OpenAPI spec) was not found in the configured `resources` roots or next to `axx.yaml`.

**Fix:** Check the path in the step, or add its directory to `resources:` in `axx.yaml`.

### AXX-E0302

**Unknown pack** · exit 2

`axx-packs.yaml` lists a pack that Axx does not publish, or one this Axx was not prepared with, or the file cannot be read. Axx prepares itself with a project's packs when it runs in the project.

**Fix:** Use the name of one of Axx's packs (see `axx pack list`), a path to a pack in the project (`./steps`) or a Go module path; `axx pack add` checks entries for you. Run Axx from the project so it can prepare the packs.

### AXX-E0303

**Packs cannot be prepared** · exit 4

The first time Axx runs with a list of packs, it prepares itself with them, downloading what it needs once. The download failed.

**Fix:** Check the network: Axx downloads from go.dev and the Go module proxy (`GOPROXY` applies). Then run again; later runs start immediately.

### AXX-E0304

**Packs do not build** · exit 2

Preparing Axx with the project's packs failed. The compiler output is in the message.

**Fix:** A pack is a Go package that exports `func Pack() core.Pack`. Fix the reported errors; `axx pack new <dir>` scaffolds a working pack.

### AXX-E0305

**Delve is needed to debug step code** · exit 4

`axx run --debug-steps` runs Axx under Delve, Go's debugger, so an IDE can stop at breakpoints in step code. `dlv` was not found on PATH or in Go's bin directories.

**Fix:** Install it with `go install github.com/go-delve/delve/cmd/dlv@latest`.

### AXX-E0306

**Delve did not start** · exit 4

`axx run --debug-steps` started Delve, but it exited or never began listening for a debugger. Its output is in the message.

**Fix:** Check that the port is free (`--debug-steps=<port>` picks another) and that Delve works on this machine (`dlv version`).

### AXX-E0310

**Unknown step id** · exit 2

`axx steps show` was given an id that no loaded pack defines.

**Fix:** List the ids with `axx steps`, or search by words with `axx steps search <words>`.

## App lifecycle

### AXX-E0400

**Invalid app configuration** · exit 2

An `apps.<name>` setting cannot be used: a bad readiness URL, address or regex, an unknown signal, or an invalid debug setting.

**Fix:** Fix the reported key; `axx schema` documents every app setting.

### AXX-E0401

**Unknown app dependency** · exit 2

`apps.<name>.dependsOn` names an app that is not declared.

**Fix:** Declare the app or remove it from `dependsOn`.

### AXX-E0402

**Dependency cycle** · exit 2

Apps depend on each other in a cycle, so no start order exists.

**Fix:** Remove one of the `dependsOn` edges in the reported cycle.

### AXX-E0403

**Unknown app** · exit 2

An app named with `--attach`, `--debug`, `axx up <app>` or similar is not declared in `axx.yaml`.

**Fix:** Use one of the app names listed in the message.

### AXX-E0404

**App has no command** · exit 2

Axx must start an app that has no `command`.

**Fix:** Add `command:`, or run the app yourself and pass `--attach <app>`.

### AXX-E0405

**App directory not found** · exit 2

`apps.<name>.dir` does not exist or is not a directory.

**Fix:** Fix `dir`; it resolves from the directory of `axx.yaml`.

### AXX-E0406

**App failed to launch** · exit 4

The app's process could not be started, typically because the executable is not on PATH.

**Fix:** Check `command` (arguments are not run through a shell unless `shell: true`).

### AXX-E0407

**App exited before ready** · exit 4

The app's process exited before its readiness checks passed. The tail of its log is included.

**Fix:** Read the log excerpt (full log under `.axx/logs/`) and run the command by hand to reproduce.

### AXX-E0408

**App not ready in time** · exit 4

The app kept running but did not pass its readiness checks within `ready.timeout`.

**Fix:** Check the readiness URL/port/log pattern, or raise `ready.timeout`. The last check result is in the message.

### AXX-E0409

**Debugger unavailable** · exit 4

Debug mode was requested but no debugger was listening, and `debug.onUnavailable` is `fail`.

**Fix:** Start the IDE debugger first (`axx ide intellij|vscode` writes the configurations), or set `onUnavailable: fallback`.

### AXX-E0410

**App could not be stopped** · exit 4

The app's process group did not exit after SIGTERM, the grace period and SIGKILL.

**Fix:** Look for processes that detach from their group; `axx down` retries using the state file.

### AXX-E0411

**App cleanup failed** · exit 4

The app's `cleanup` command exited non-zero. The run still completed; this is reported so leaks are visible.

**Fix:** Run the cleanup command by hand to see its output.

### AXX-E0412

**No active tags** · exit 2

Active startup is on with `onNoTags: error`, and the selected scenarios carry no tags, so Axx cannot tell which apps to start.

**Fix:** Tag the scenarios, set `active.onNoTags: fallback` (start everything), or disable active startup.

### AXX-E0413

**Run state file error** · exit 4

`.axx/run/state.json` (used by `axx up`/`axx down` to find running apps) could not be read or written.

**Fix:** Check permissions on `.axx/`; deleting the stale file is safe when no apps are running.

### AXX-E0414

**Startup interrupted** · exit 130

Starting apps was interrupted (Ctrl-C). Every app that had started was stopped and cleaned up.

**Fix:** Nothing to fix; re-run when ready.

## Reporters

### AXX-E0600

**Unknown reporter** · exit 2

`--format` or `run.reporters` names a reporter that does not exist.

**Fix:** Use one of: pretty, progress, compact, junit, messages, cucumber-json, html, agent.

## Lint

### AXX-E0800

**No lint rules** · exit 2

`axx.yaml` has a `lint` section, but it (with its includes) defines no rules, so `axx lint` would check nothing.

**Fix:** Add rules under `lint.rules`, or include a rules file with `lint.include`. Remove the `lint` section if the project has no isolation rules.

### AXX-E0801

**Lint include not found** · exit 2

A file named in `lint.include` (or in an included file's `include`) does not exist. Includes resolve relative to the file that lists them.

**Fix:** Fix the path. If the file is generated (`axx-lint.generated.yaml`), run `axx fixtures generate` first.

### AXX-E0802

**Lint include cycle** · exit 2

A lint rules file is included more than once, for example two files that include each other. Every file may be loaded once.

**Fix:** Remove the repeated include.

### AXX-E0803

**Invalid lint include** · exit 2

An included lint rules file is not valid YAML, has keys the lint section does not allow, or has a `config:` block (only the including file configures lint).

**Fix:** Keep only `rules:` and `include:` in included files, in the same format as the `lint` section of `axx.yaml`. The message lists each problem with its line.

### AXX-E0804

**Invalid lint configuration** · exit 2

A lint rule cannot be used: a missing `regex` (or `jsonPath` for `type: jsonpath`), a regex that is not valid Java syntax or has no capture group, an invalid glob or JSONPath, no `filePatterns`, or a `config.baseDir` that is not a directory.

**Fix:** Fix the reported key. Regexes use Java syntax and extract their first participating capture group, e.g. `id:\s*"([^"]+)"`.

### AXX-E0805

**Invalid lint option** · exit 2

`axx lint --format` names an unknown format, `--mode` is not `error` or `warn`, or an output file cannot be written.

**Fix:** Use `--format human|json|junit|sarif|github` (optionally `NAME:FILE`) and `--mode error|warn`.

### AXX-E0810

**File cannot be evaluated** · exit 3

A file selected by a `type: jsonpath` rule is not valid JSON (or the JSONPath cannot be evaluated over it), so its values cannot be checked. This fails the rule even in warn mode.

**Fix:** Fix the JSON at the reported line, or narrow the rule's `filePatterns`/`excludePatterns` so it only selects JSON files.

### AXX-E0811

**File cannot be read** · exit 3

A file selected by a lint rule could not be read (permissions, or it disappeared during the run).

**Fix:** Check the file's permissions, or exclude it with `excludePatterns`.

### AXX-E0812

**File skipped: too large** · exit 0

A file selected by a lint rule is larger than `lint.config.maxFileSize` (default 5 MB) and was not checked. This is a warning.

**Fix:** Narrow the rule's `filePatterns`, or raise `lint.config.maxFileSize`.

### AXX-E0820

**Duplicate test data** · exit 3

A value that a lint rule requires to be unique occurs more than once: anywhere (`global-unique`), within one file (`file-unique`), or in more than one file (`cross-file-unique`). Scenarios running in parallel against shared infrastructure collide on such values.

**Fix:** Give each occurrence its own value (for example prefix ids with the scenario or file name). If the value is intentionally shared, add it to the rule's `ignoreValues`; if the rule is too strict, change its `validation`. `mode: warn` reports without failing.

### AXX-E0830

**SQL ordinal addresses a missing entry** · exit 0

A step addresses the Nth selection (or trigger) of the scenario, but fewer than N were retrieved (or created) before it, counting every database service. The step always fails at runtime. This is a warning.

**Fix:** Retrieve the selection before asserting on it, or use the ordinal of an earlier retrieval. Selections and triggers are numbered in the order the scenario creates them.

### AXX-E0831

**SQL ordinal label does not match** · exit 0

A retrieval (or trigger) step is labelled with an ordinal it cannot have: selections and triggers are appended in the order they are created, and the ordinal in a creating step is only a label. Later steps that use the label address another entry. This is a warning.

**Fix:** Number retrievals in the order they happen (1st, 2nd, 3rd ...), per database service, and address them by that number.

## Fixtures

### AXX-E0900

**Invalid fixtures configuration** · exit 2

The fixtures section of axx.yaml cannot be used: a `sources` root does not exist, lies inside `baseDir` or contains it, a glob is malformed, a conformance rule names an unknown family, or two families or expression functions claim one name.

**Fix:** Fix the fixtures section of axx.yaml; sources roots are relative to `fixtures.baseDir` and must be disjoint from it.

### AXX-E0901

**Invalid fixture spec** · exit 2

A `*.factory.yaml`, `*.fixture.yaml` or `*.prototype.yaml` file is malformed (unknown field, wrong type, empty factory), cannot be bound to a factory, claims a fixture key twice, names an unsupported family, or declares an identity without a path.

**Fix:** The message names the file. `axx schema --kind factory|fixture|prototype` prints the formats; bind a fixture explicitly with `factory: <root-relative-path>`.

### AXX-E0902

**Fixture generation failed** · exit 1

Expanding the specs failed: a required field no layer resolves, a value of the wrong type, an unknown field, a schema oracle rejecting the output, an identity collision, a `$ref` that resolves to nothing, or an expression that cannot be evaluated.

**Fix:** Fix the factory sources (defaults:, prototype, fixture data) as the message says, then run `axx fixtures generate`.

### AXX-E0903

**Hand-edited managed file** · exit 1

`axx fixtures generate` refused to overwrite managed files whose content no longer matches the sha256 in axx-fixtures.manifest.yaml (or the pairings lock was edited).

**Fix:** Lift the change into the factory spec (or re-adopt the file), or revert the file. There is no force option that discards edits.

### AXX-E0904

**Fixture check failed** · exit 1

`axx fixtures check` found a managed file that differs from what its factory generates (drift), a missing ignored output, or a manifest that does not list exactly what the factories produce.

**Fix:** Edit the factory sources, not the generated files, and run `axx fixtures generate`; commit the result.

### AXX-E0905

**Adoption refused** · exit 1

`axx fixtures adopt` refused: the files are already managed, the factory exists, fixture keys collide, the glob matches nothing, the family cannot adopt, or regenerating from the adopted spec would change a file's data. Nothing was written.

**Fix:** Fix the cause the message names and run adopt again; `--dry-run` verifies without writing.

### AXX-E0906

**Version control command failed** · exit 4

`axx fixtures untrack` could not run `git ls-files` or `git rm --cached` (the tool is missing, the directory is not a work tree, or it timed out).

**Fix:** Run it inside the repository that holds the fixtures, with git on PATH.

### AXX-E0907

**Fixture schema unusable** · exit 2

A governing schema (Avro .avsc, JSON Schema, OpenAPI component, XSD, .proto or descriptor set, SQL DDL) cannot be read or compiled, or the reference form is not supported (classpath: and class: refs need a JVM).

**Fix:** Check the path: factory.schema is relative to the factory file, a conformance rule's schemaRef to fixtures.baseDir.

### AXX-E0908

**Fixture file I/O error** · exit 1

A fixture, spec, manifest or output file could not be read or written.

**Fix:** Check that the path exists and that its permissions allow reading and writing.

### AXX-E0909

**Invalid adopt options** · exit 2

`axx fixtures adopt` needs either --schema, --files and --factory, or --into and --files.

**Fix:** Run `axx fixtures adopt --help`.