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