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: yksanjo/gmem

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

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

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