How to Debug a Failed no-mistakes Pipeline Run Using the axi CLI

Use no-mistakes axi status to identify the failing step and no-mistakes axi logs --step <step> to view detailed error output, then either resolve the issue with axi respond or terminate the run with axi abort.

The no-mistakes automation framework provides a command-line interface called axi for managing pipeline runs. When a pipeline fails or pauses at a review gate, the axi CLI in the kunchenguid/no-mistakes repository offers direct access to execution state, step logs, and control signals without requiring manual database manipulation.

Understanding the axi CLI Architecture

The axi CLI is implemented as a thin wrapper around the daemon’s RPC interface. Commands are dispatched from internal/cli/axi.go, while specialized sub-packages handle specific operations:

• internal/cli/axi_render.go – Formats the TOON (JSON-like) representation for status output
• internal/cli/axi_query.go – Queries the daemon for run metadata and step logs via ReadLogsForStep
• internal/cli/axi_drive.go – Processes gate responses and updates the database through db.SetRunAwaitingAgent

All run state persists in an SQLite database located at $NM_HOME/state.db, specifically in the run_logs table and the awaiting_agent_since column defined in internal/db/run.go.

Checking Active Run Status

Start debugging by verifying whether an active run exists and identifying its current state.

no-mistakes axi

The home view displays the current branch, any active run ID, and the next suggested action. If a run is paused, the output includes an awaiting_agent marker indicating the run is parked at a gate.

For detailed inspection, use:

no-mistakes axi status

This outputs a TOON representation containing a steps map where each step includes a status field (pending, running, awaiting_approval, failed) and an optional error string. The awaiting_agent field (set in internal/pipeline/executor.go at line 377) displays the duration the run has been parked, cleared automatically once a response is processed.

{
  "id": "8f3c2a1",
  "branch": "feature/fix",
  "status": "awaiting_approval",
  "awaiting_agent": "parked 2m15s",
  "steps": {
    "review": { "status": "awaiting_approval" },
    "test": { "status": "pending" }
  }
}

Inspecting Step Logs

When a step reports an error, retrieve the full output without re-running the pipeline:

no-mistakes axi logs --step review --full
no-mistakes axi logs --step test --full

The log collector writes entries to the SQLite run_logs table (managed in internal/db/run_log.go). The CLI retrieves these via ReadLogsForStep in internal/cli/axi_query.go, streaming the raw output directly to your terminal. This is the fastest method to diagnose why a specific step failed without executing the entire pipeline again.

Responding to Paused Gates

If axi status shows awaiting_approval, the run is parked at a review gate awaiting manual intervention.

Approve the current gate:

no-mistakes axi respond --action approve

Fix specific findings with instructions:

no-mistakes axi respond --action fix --findings r1,r2 --instructions "apply the suggested patch"

The driver (internal/cli/axi_drive.go) validates arguments, writes the response into the run’s database, and clears the awaiting_agent_since field. The executor (internal/pipeline/executor.go) then resumes processing the next step. The handshake logic is verified in internal/e2e/executor_approval_test.go.

Aborting Stuck Runs

Terminate a failed or unwanted run using the abort command:

no-mistakes axi abort               # Abort current branch run

no-mistakes axi abort --run <id>    # Abort specific run by ID

Internally, internal/cli/axi.go calls the daemon’s ipc.MethodCancelRun, which invokes RunManager.HandleCancel. The abort path is idempotent: if the run does not exist, the command exits cleanly. This behavior is confirmed in TestAbortByRunIDReapsRunFromOutsideWorktree, allowing you to cancel runs from anywhere, even outside the worktree.

Common Failure Scenarios and Diagnostic Patterns

Symptom	Likely Cause	Diagnostic Command
Run stops at gate	Review step awaiting manual approval	axi status shows awaiting_agent flag
Force-push rejected	Remote branch advanced since run start	Check error field in push step; see internal/pipeline/steps/forcepush.go
Permission denied in logs	Daemon lacks proper $NM_HOME access	Verify echo $NM_HOME and daemon status
Abort has no effect	No active run on current branch	axi home view reports "no active run"

Summary

• Use no-mistakes axi status to view the TOON representation and identify awaiting_agent states
• Query specific step failures with no-mistakes axi logs --step <name> --full, which reads from the SQLite run_logs table via internal/cli/axi_query.go
• Resume gated runs using no-mistakes axi respond; the driver updates awaiting_agent_since in internal/cli/axi_drive.go
• Terminate runs with no-mistakes axi abort, which calls ipc.MethodCancelRun and RunManager.HandleCancel
• Check $NM_HOME/state.db directly only when CLI introspection is insufficient; most debugging completes within the axi interface

Frequently Asked Questions

How do I check if a no-mistakes pipeline run is currently waiting for approval?

Run no-mistakes axi status and examine the awaiting_agent field. If present, the run is parked at a gate and the executor in internal/pipeline/executor.go has set the awaiting_agent_since timestamp. The status will also show status: awaiting_approval for the specific step that triggered the pause.

Where are the pipeline logs stored when using the axi CLI?

Logs are stored in an SQLite database at $NM_HOME/state.db in the run_logs table. The axi logs command retrieves these entries through ReadLogsForStep in internal/cli/axi_query.go, avoiding the need to interact with the database file directly.

Can I abort a no-mistakes pipeline run from outside the repository directory?

Yes. Use no-mistakes axi abort --run <id> with the specific run identifier. According to the source code in internal/cli/axi.go, this bypasses the worktree check and calls the daemon’s cancellation directly via ipc.MethodCancelRun, allowing you to reap runs from any location.

Why does my axi logs command return "permission denied"?

This error typically indicates the daemon process lacks read permissions on $NM_HOME/state.db or the environment variable is misconfigured. Verify that NM_HOME points to the correct state directory and ensure the daemon is running with no-mistakes daemon status before attempting to query logs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}