Exit and 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.