Skip to main content
Glama

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

Related MCP server: Pentagonal

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

  • M1 — npm package, log parser, Anchor error database

  • M2 — CPI call stack visualizer, IDL integration

  • M3 — VS Code extension (inline hints)


License

MIT

A
license - permissive license
-
quality - not tested
F
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/konradbachowski/anchor-debug'

If you have feedback or need assistance with the MCP directory API, please join our Discord server