anchor-debug

CLI tool that makes Anchor program failures understandable.

When your Anchor test fails with custom program error: 0x1770, anchor-debug tells you exactly what broke, where, and why.

Before vs After

Without anchor-debug:

Error: failed to send transaction: Transaction simulation failed: Error processing Instruction 0: custom program error: 0x7d2

With anchor-debug:

✗ Transaction failed

  Error: ConstraintHasOne
  Code:  0x7d2 (2002)
  Msg:   A has_one constraint was violated — account field does not match expected value
  Program: my_program (9uvbWC...)

  CPI call stack:
  └─ ✗ my_program (9uvbWC...) ← failed here
     Error: A has_one constraint was violated — account field does not match expected value
     └─ ✓ TokenkegQfeZy... (Token Program)
     └─ ✗ my_program::validate_authority ← failed here

Installation

npm install -g anchor-debug
# or use directly with npx
npx anchor-debug --help

Usage

Pipe anchor test output

anchor test 2>&1 | npx anchor-debug

anchor-debug reads stdin, finds the failure, and prints a human-readable error. If the test succeeds, output is passed through unchanged.

Debug a transaction by signature

npx anchor-debug tx <SIGNATURE> --cluster devnet
npx anchor-debug tx <SIGNATURE> --cluster mainnet-beta
npx anchor-debug tx <SIGNATURE> --cluster http://localhost:8899

Fetches the transaction from the RPC, extracts its logs, and formats the error.

Run tests with automatic error formatting

npx anchor-debug test
npx anchor-debug test --skip-build

Runs anchor test for you and prints the parsed error on failure.

Options

| Flag | Description | |---|---| | --raw | Also show raw log lines | | -v, --verbose | Show all program log messages | | -c, --cluster <cluster> | Cluster or RPC URL (tx command) | | --skip-build | Pass --skip-build to anchor test |

How it works

1. Log parser — reads Solana program logs line-by-line using a regex state machine
2. Error database — 60+ Anchor framework errors mapped by hex code (both new 0x7d0+ and legacy 0x1770+ ranges)
3. CPI tracer — rebuilds the full Program invoke [N] call tree and marks the innermost failing invocation
4. IDL resolver — reads Anchor.toml and target/idl/*.json to show program names instead of pubkeys

Supported error ranges

| Range | Source | |---|---| | 0x64–0x67 (100–103) | Instruction errors | | 0x3e8–0x3ea (1000–1002) | IDL errors | | 0x7d1–0x7f8 (2001–2040) | Constraint errors (Anchor ≥ 0.24) | | 0xbb8–0xbc1 (3000–3017) | Account errors | | 0xfa0–0xfa2 (4000–4002) | State errors | | 0x1770–0x1783 (6000–6019) | Legacy constraint errors (Anchor < 0.24) |

MCP Server (for AI agents)

anchor-debug works as an MCP server, giving AI coding agents (Claude Code, Cursor, etc.) structured access to Solana error data.

Add to .mcp.json in your project:

{
  "mcpServers": {
    "anchor-debug": {
      "command": "npx",
      "args": ["anchor-debug", "mcp"]
    }
  }
}

Or globally in ~/.claude/mcp.json.

Available tools:

| Tool | What it does | |---|---| | parse_logs | Takes raw log lines → structured error + CPI stack | | debug_transaction | Takes signature + cluster → fetches and parses | | lookup_error | Takes hex code → error name + message |

Example agent response after calling parse_logs:

{
  "failed": true,
  "error": {
    "name": "ConstraintHasOne",
    "code": 2002,
    "hex": "0x7d2",
    "message": "A has_one constraint was violated — account field does not match expected value",
    "category": "constraint"
  },
  "failedProgram": "my_program",
  "failedNode": {
    "program": "my_program",
    "depth": 2,
    "errorMessage": "A has_one constraint was violated"
  },
  "cpiStack": [...]
}

Instead of reasoning about 0x1770, the agent immediately knows what failed and can fix it in one shot.

Programmatic API

import { parseLogsFromString, formatResult } from "anchor-debug";

const logs = [
  "Program MyProg invoke [1]",
  "Program MyProg failed: custom program error: 0x7d2",
];

const parsed = parseLogsFromString(logs.join("\n"));
console.log(formatResult(parsed));

Milestones

• [x] M1 — npm package, log parser, Anchor error database
• [x] M2 — CPI call stack visualizer, IDL integration
• [ ] M3 — VS Code extension (inline hints)

License

MIT