Troubleshooting

This page covers failures that the current CLI can produce. For command syntax, compare against axp --help and the command-specific --help output.

axp: command not found after install

The installer writes the wrapper to ~/.fiveonefour/bin/axp by default. If that directory is not already on PATH, the installer prints the export to add and, for writable zsh or bash config directories, appends an installer-managed entry.

Open a new shell, reload your shell config, or add the path manually:

export PATH="$HOME/.fiveonefour/bin:$PATH"
axp --help

If you installed with FIVEONEFOUR_HOME=<path>, use <path>/bin instead.

Install download fails

The installer requires curl and downloads the version manifest, binary, checksum, and optional signature from https://download.514.ai with curl -fsSL. If the manifest download fails, the script prints the failed manifest URL and the underlying curl error.

Check that curl is installed and that your network, proxy, or firewall can reach the download host:

curl -fsSL https://download.514.ai/stable/index.json >/dev/null

Then rerun the installer. If the binary or checksum download fails after the manifest succeeds, retry the install and keep the printed download URL for debugging.

Unsupported OS or architecture

The installer has prebuilt targets for:

• macOS arm64 and x86_64
• Linux arm64/aarch64 and x86_64/amd64

On any other uname -s and uname -m pair, it exits with unsupported platform: <os>/<arch>. Use one of the supported platforms for the hosted installer.

Uninstall leaves a PATH entry

By default, uninstall removes the AXP wrapper and cached versions but leaves shell startup files untouched. To remove exact installer-managed PATH entries from ~/.zshrc, ~/.bashrc, ~/.bash_profile, and ~/.profile, pass --remove-path:

bash <(curl -fsSL https://download.514.ai/uninstall.sh) --yes --remove-path

The script only removes lines that exactly match the installer-managed ~/.fiveonefour/bin export, plus the adjacent # AXP CLI comment when present. Remove custom PATH edits manually.

Uninstall skips the axp binary

The uninstall script only removes ~/.fiveonefour/bin/axp automatically when it looks like the hosted installer wrapper. If that file is a custom binary, symlink, or a Cargo-installed axp, uninstall prints that it was skipped.

Pass --force only when you intentionally want to remove that file anyway:

bash <(curl -fsSL https://download.514.ai/uninstall.sh) --yes --force

Cargo-installed binaries outside ~/.fiveonefour/bin are not removed by the hosted uninstall script.

Non-interactive uninstall fails

Interactive uninstall prompts before removing files. In a non-interactive shell, the script refuses to continue unless you pass --yes:

bash <(curl -fsSL https://download.514.ai/uninstall.sh) --yes

Combine it with other flags when needed, for example --yes --remove-path.

Preview uninstall changes

Use --dry-run to print what uninstall would remove or update without changing files. Dry runs do not require confirmation and print Dry run: no files will be changed.

bash <(curl -fsSL https://download.514.ai/uninstall.sh) --dry-run --remove-path

No command was provided

axp requires a subcommand. Running it with no command exits non-zero and prints usage.

axp --help

Experiment YAML does not validate

axp validate <EXPERIMENT> prints Validated <EXPERIMENT> and a suggested axp run <EXPERIMENT> command on success. On schema failure, it prints one error line and exits non-zero. It may also print non-fatal warning[<rule>] lint messages to stderr while still exiting zero.

Common schema issues include:

• schema_version is not 1.
• id, variant IDs, or test names are not kebab-case.
• name, flow.prompt, model, variant tags, or test scripts are empty.
• matrix.variant has no entries.
• tests.application and tests.introspection are both empty.
• limits.max_turns, limits.max_time_seconds, or limits.max_cost_usd are zero or invalid.
• The YAML contains an unknown field.

max_cost_usd must be a positive number, but this build does not abort a running agent when reported cost reaches that value. max_time_seconds is enforced by AXP, and max_turns is passed to Claude Code.

Run validation before starting containers:

axp validate experiment.yaml

If you see warning[polls-for-file-in-setup], check any variant overrides.setup loop that waits for a /workspace/... path. Variants are isolated, so each variant must create or fetch its own setup files.

A run used the wrong variant set

axp run --variant <ID> only accepts IDs from matrix.variant. If a requested variant does not exist, the CLI prints the known variant IDs and exits with code 2.

Use a local dry run to inspect the planned variants without creating containers or making API calls:

axp local run experiment.yaml --dry-run

--repeat 0 fails

--repeat must be at least 1.

axp run experiment.yaml --repeat 3

Required secrets are missing

Only secrets declared by the experiment are resolved and injected, and only by axp local run — the platform path (axp run) rejects experiments that declare secrets. If a declared secret is missing from every source, the local run fails before execution.

Provide secrets through one of the supported sources:

# Auto-loaded when present in the current directory.
echo "GITHUB_TOKEN=..." > .env

# Explicit dotenv file.
axp local run experiment.yaml --env-file .env.local

# Host environment.
GITHUB_TOKEN=... axp local run experiment.yaml

# Highest precedence CLI override.
axp local run experiment.yaml --env GITHUB_TOKEN=...

Secret names must match POSIX environment variable syntax: ^[A-Z_][A-Z0-9_]*$. Harness-managed names cannot be declared as experiment secrets, including ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, OPENAI_API_KEY, OPENAI_BASE_URL, MODEL, MAX_TURNS, IS_SANDBOX, TRACEPARENT, names starting with AXP_, names starting with CLAUDE_CODE_, names starting with CODEX_, and names starting with OTEL_.

Anthropic API key is missing

axp run uses platform-supplied model access, so it needs no host model key. Local runs do: axp local run requires a model credential in the host environment for the selected agent — ANTHROPIC_API_KEY for Claude or OPENAI_API_KEY for Codex. These are harness-managed, so do not list them under experiment secrets.

export ANTHROPIC_API_KEY=...
axp local run experiment.yaml

export OPENAI_API_KEY=...
axp local run codex-experiment.yaml

If you are using AXP-provided model access, make sure the CLI is logged in with axp auth login or has AXP_API_KEY set. You do not need to set Anthropic or OpenAI API keys for that run.

No runs are listed

axp list shows local runs from ./.axp/runs/ and, when signed in, remote platform runs. If no local runs exist in the current directory and no remote runs match, it prints an empty-list message.

Run a local experiment from the project directory that should own the results:

axp local run experiment.yaml
axp list

axp list shows no runs

Use axp list --local to check only ./.axp/runs/. If it is empty, run a local experiment first. Interrupted local runs are still listed with status partial. Inspect a run's artifacts directly under .axp/runs/<run-id>/, or query them with axp local query <run-id> "<SQL>".

To inspect platform results locally, download the run first:

axp download my-experiment-01HX...

Docker image pull fails

axp local run pulls axp-base from Docker Hub (514labs/axp-base) on first use. If the pull fails, check Docker is running and Docker Hub is reachable; you can pre-pull manually:

docker pull 514labs/axp-base:latest

Use axp local run --dry-run when you only want experiment validation without touching containers. (Platform runs with axp run need no local Docker.)

axp run says you're not signed in

axp run submits to the platform, so it needs saved credentials. If you see an authentication error, sign in (or set AXP_API_KEY in CI):

axp auth login
axp auth whoami

To run without the platform, use axp local run (Docker plus your own model key).

axp run rejects an experiment that declares secrets

The platform path does not yet deliver experiment secrets, so axp run rejects any experiment that declares them (top-level or in a variant overrides.secrets). Run it locally, where --env / --env-file inject the values:

axp local run experiment.yaml --env-file .env.local

See Running experiments and Environment and Auth.

Cancel a platform run

axp run prints a run id. Cancel queued or in-flight jobs with it:

axp cancel <run-request-id>

Cancel only specific jobs with --run <run-id> (comma-separated); the default cancels every job in the request.

Not logged in for platform upload

axp upload requires credentials saved by axp auth login. If credentials are missing, run:

axp auth login
axp auth whoami

axp auth whoami round-trips through the platform API and prints the resolved user and active org. Use axp auth orgs to list available orgs, and axp auth orgs --switch org_... to change the active CLI org.

The credentials file lives at ~/.fiveonefour/axp/credentials.toml. AXP_API_KEY can override the saved API key.

Upload target is wrong

Auth, upload, and download requests go to the AXP platform by default. If the AXP team gives you a different platform URL, set AXP_PLATFORM_URL:

AXP_PLATFORM_URL=https://platform.example.com axp upload my-experiment-01HX...

Active org is wrong

Platform commands use the active CLI org by default. Check it with:

axp auth whoami
axp auth orgs

Switch the active org with:

axp auth orgs --switch org_...

For a one-off upload or download without changing the active org, pass --org:

axp upload my-experiment-01HX... --org org_...
axp download my-experiment-01HX... --org org_...

If a run exists in another org that your API key can access, the platform error includes this hint. If the run is not in an accessible org, the error does not reveal where it exists.

Run was already uploaded

If the server reports that a run already exists, pass --force to overwrite that upload:

axp upload my-experiment-01HX... --force

Download destination already exists

axp download writes to .axp/downloads/<run-id>/ and refuses to replace an existing directory unless you pass --force:

axp download my-experiment-01HX... --force

Local query derivation fails

Use axp local query to derive query files from a raw local run, or to read downloaded platform Parquet, and surface the conversion/query error:

axp local query <run-id> "SELECT * FROM runs LIMIT 1"

If the run is not local, use axp list to find local runs or run axp download <run-id> before querying locally.