DEV Community: TobiasBond

Anchor Error Codes: Complete Reference Guide (100–4200)

TobiasBond — Mon, 09 Mar 2026 00:37:00 +0000

If you've built on Solana with Anchor, you've seen errors like
Error Code: 2003 with no clear explanation of what went wrong
or how to fix it.

This guide covers every official Anchor error code — what it
means, why it happens, and how to fix it.

How Anchor Error Codes Are Structured

Anchor errors follow a numbered system across 6 categories:

100–103 — Instruction errors
1000–1002 — IDL errors
1500 — Event errors
2000–2029 — Constraint errors (most common)
3000–3017 — Account errors
4000–4200 — State errors

Constraint Errors (2000–2029) — The Ones You'll Hit Most

2000 — ConstraintMut

Message: A mut constraint was violated

Cause: You're trying to modify an account not marked as mut

Fix: Add #[account(mut)] to the account in your instruction context

#[derive(Accounts)]
pub struct MyInstruction<'info> {
    #[account(mut)]  // <- add this
    pub my_account: Account<'info, MyData>,
}

2001 — ConstraintHasOne

Message: A has_one constraint was violated

Cause: A field on your account doesn't match the expected pubkey

Fix: Make sure the account's field matches the signer or related account

#[account(has_one = authority)]
pub data_account: Account<'info, MyData>,
pub authority: Signer<'info>,

2002 — ConstraintSigner

Message: A signer constraint was violated

Cause: Account expected to sign but didn't

Fix: Ensure the account is a Signer type and the client passes it as a signer

2003 — ConstraintRaw

Message: A raw constraint was violated

Cause: Custom constraint expression evaluated to false

Fix: Debug your constraint = expression — add logs to check values

#[account(constraint = some_account.value > 0 @ MyError::InvalidValue)]

2006 — ConstraintOwner

Message: An owner constraint was violated

Cause: Account is owned by a different program than expected

Fix: Verify you're passing the correct account owned by your program

2012 — ConstraintSeeds

Message: A seeds constraint was violated

Cause: PDA address doesn't match the provided seeds + bump

Fix: Make sure seeds and bump on-chain match exactly what you used to derive the PDA client-side

// On-chain
#[account(seeds = [b"vault", user.key().as_ref()], bump)]

// Client-side — must match exactly
const [vault] = PublicKey.findProgramAddressSync(
  [Buffer.from("vault"), user.publicKey.toBuffer()],
  programId
)

Account Errors (3000–3017)

3000 — AccountDiscriminatorAlreadySet

Message: Account discriminator already set

Cause: Trying to initialize an account that's already initialized

Fix: Check if account exists before calling init instruction

3001 — AccountDiscriminatorNotFound

Message: Account discriminator not found

Cause: Account data is empty — account probably doesn't exist

Fix: Confirm the account is created and has data before fetching

3003 — AccountDidNotDeserialize

Message: Failed to deserialize the account

Cause: Account data doesn't match your struct layout

Fix: Check if the account was initialized with a different version of your program

3007 — AccountNotInitialized

Message: The given account is not initialized

Cause: Account has no data / wrong account passed

Fix: Make sure you're passing the right account address

3012 — AccountNotMutable

Message: The given account is not mutable

Cause: Trying to write to an account without marking it mutable

Fix: Pass the account with isMutable: true on the client side

Instruction Errors (100–103)

100 — InstructionMissing

Cause: 8-byte discriminator not found — wrong instruction or corrupted data

Fix: Verify you're calling the right instruction name

101 — InstructionFallbackNotFound

Cause: Fallback function called but not defined

102 — InstructionDidNotDeserialize

Cause: Instruction data couldn't be deserialized — argument mismatch

Fix: Check that client-side arguments match the instruction signature exactly

103 — InstructionDidNotSerialize

Cause: Return value couldn't be serialized

State Errors (4000–4200)

4000 — IdlInstructionStub

Cause: IDL instruction called but not implemented

4100 — EventInstructionStub

Cause: Event CPI called but handler not implemented

Quick Reference — Top 10 Errors

Code	Name	One-Line Fix
2000	ConstraintMut	Add `#[account(mut)]`
2001	ConstraintHasOne	Field must match related account pubkey
2002	ConstraintSigner	Account must sign the transaction
2003	ConstraintRaw	Custom constraint expression is false
2006	ConstraintOwner	Wrong program owns this account
2012	ConstraintSeeds	Seeds/bump mismatch between client and program
3000	AccountDiscriminatorAlreadySet	Account already initialized
3001	AccountDiscriminatorNotFound	Account doesn't exist yet
3007	AccountNotInitialized	Wrong account address passed
3012	AccountNotMutable	Pass account as mutable on client

Full Reference PDF

This article covers the most common errors. I put together a
complete PDF handbook covering all 59 Anchor error codes with
full explanations, root causes, fixes, and code examples:

Anchor Error Handbook — Complete Reference (100–4200)

Useful if you want everything in one searchable document you
can keep open while building.

How I Built a Cost Proxy to Stop OpenClaw from Burning My API Budget

TobiasBond — Sat, 28 Feb 2026 15:31:52 +0000

If you've been in the OpenClaw community for more than a week, you've seen the posts.

"$3,600/month on API calls."
"Woke up to a $200 bill from a heartbeat loop running all night."
"I have zero visibility into what my agent is spending."

OpenClaw is one of the most exciting open-source projects of 2026 — 210K+ GitHub stars, a personal AI agent that actually does things. But the moment you give an AI agent unrestricted access to paid APIs, you're playing with fire.

I kept seeing these horror stories and realized nobody had built a proper solution. There are a few monitoring tools out there (ClawMetry gives you read-only stats, Tokscale is CLI-only), but nothing that actually stops the bleeding in real time.

So I built TokPinch.

What TokPinch Does

TokPinch is a transparent proxy that sits between OpenClaw and your LLM provider (Anthropic, OpenAI). Every API request passes through it.

Setup is literally one line in your OpenClaw config:

ANTHROPIC_BASE_URL=http://localhost:4100/v1

That's it. Your agent doesn't know TokPinch exists. But now you have:

Real-time cost tracking — every request logged with model, tokens, cost, and session
Budget enforcement — set daily/monthly limits that actually block requests when exceeded
Loop detection — catches runaway agents (rapid fire, repeated content, cost spirals, heartbeat storms) and pauses them automatically
Smart model routing — automatically downgrades cheap tasks (heartbeats, short messages) from Opus to Haiku, saving 10-50%
Telegram/email alerts — get notified the second something goes wrong
A dashboard that doesn't suck — dark mode, real-time WebSocket updates, cost charts, budget gauges

The Architecture

I wanted TokPinch to be fast, self-hosted, and have zero dependencies on external services.

OpenClaw → TokPinch (localhost:4100) → Anthropic/OpenAI
                ↓
         SQLite (metadata only)
                ↓
         React Dashboard + WebSocket
                ↓
         Telegram/Email Alerts

The tech stack:

TypeScript — end to end, because life is too short for runtime type errors
Fastify — fastest Node.js HTTP framework, perfect for a proxy
SQLite (better-sqlite3) — zero config, WAL mode for concurrent reads, file-based so it deploys anywhere
React 18 + Vite + Tailwind — for the dashboard
Docker — multi-stage build, runs as non-root with read-only filesystem

The key design decision: TokPinch never stores API keys or message content. Keys pass through in headers and are discarded immediately. Only metadata hits the database (model name, token counts, cost, timestamp, session ID). This is documented in our SECURITY.md.

Building the Loop Detector

This was the most interesting engineering challenge. OpenClaw agents can get stuck in loops — the infamous heartbeat bug, where the agent sends the same message repeatedly, burning through your budget at 20+ requests per minute.

I implemented four detection rules:

Rapid fire — more than 20 requests per minute from the same session
Repeated content — same message hash appearing 5+ times in 5 minutes (uses djb2 hash on first 200 chars)
Cost spiral — more than $2 spent in a 5-minute window
Heartbeat storm — 10+ heartbeat-pattern messages in 10 minutes

When any rule triggers, TokPinch pauses that session with exponential backoff (starting at 5 minutes, doubling up to 30 minutes). The agent gets a clear error message, and you get a Telegram alert.

🔄 Loop detected! Session loop-test sent identical content 6 times 
in 5 minutes. Spending $0.0000. Paused for 5 minute(s).

The circular buffer approach keeps memory usage constant — 100 slots per session, O(1) lookups.

Smart Model Routing

This is the feature that saves real money. Not every API call needs the most expensive model.

When OpenClaw sends a heartbeat ping or a short message like "hi" to Claude Opus ($15/MTok input), TokPinch intercepts it and routes to Haiku ($0.80/MTok input) instead. The response quality for trivial tasks is identical, but the cost drops by ~95%.

The routing rules are configurable:

Route to cheap model when: message is under 200 tokens, no tools/images/documents, system prompt under 500 tokens
Never downgrade when: user explicitly set the model, images or documents are present, more than 5 tools are being used

During testing, a request to claude-opus-4 with just "hi" was correctly routed to claude-haiku-4-5, confirmed in the server logs:

🔀 Routed: claude-opus-4 → claude-haiku-4-5-20251001 (low_token_chat, saved ~$0.0037)

Security: Built for the OpenClaw Crisis

Security isn't an afterthought — it's a feature. OpenClaw has had a rough security track record: one-click RCE, 824+ malicious skills on ClawHub, 42,000+ exposed instances. TokPinch sitting in the API request path means it must be bulletproof.

What we did:

API keys are never stored or logged — pino logger has redact paths for all auth headers
Zero message content on disk — the requests table schema literally has no column for it
Docker runs as non-root with read-only filesystem and no-new-privileges
JWT auth with auto-generated 512-bit secrets
Rate limiting on every endpoint (proxy, API, and login)
Content-Security-Policy, X-Frame-Options, HSTS headers on all responses
Test endpoints auto-disabled in production

The full audit is in SECURITY.md.

The Dashboard

I wanted the dashboard to feel like a proper product, not a developer afterthought. Dark theme (zinc-950 base), JetBrains Mono for numbers, Outfit for headings, real-time WebSocket updates, Framer Motion animations.

Overview — 4 stat cards, cost-over-time chart, model breakdown, budget gauges, live request feed

Sessions — every session with cost, request count, tokens, and the most-used model. Expandable rows showing individual requests.

Budget — arc gauges showing spend vs. limit, status badges (ACTIVE/WARNING/PAUSED/OVERRIDE), one-click resume after manual review.

Alerts — all budget warnings, loop detections, and daily digests with filter tabs and delivery status.

What I Learned

Native modules on Windows are painful. better-sqlite3 needs to be compiled for your exact Node.js version. Switching Node versions (via nvm) breaks the binary. Solution: always npm rebuild after version changes.
Streaming proxies are tricky. SSE (Server-Sent Events) responses from Anthropic need to be intercepted without buffering — you want zero-latency passthrough while still accumulating usage data from the final event. The SSEInterceptor Transform stream handles this.
Test with real money before shipping. Mock tests proved the code worked. Real Anthropic API calls found two critical bugs: a wrong default model ID in routing rules, and a missing anthropic-version header that the proxy wasn't injecting. Both would have broken every user's setup.
Security documentation is a feature. In the OpenClaw ecosystem where trust is low (malicious skills, exposed instances), having a thorough SECURITY.md that explains exactly how API keys are handled makes people comfortable using your tool.

Try It

TokPinch is 100% free and open source (MIT licensed).

Quick start:

docker run -p 4100:4100 -v tokpinch-data:/app/data \
  -e DASHBOARD_PASSWORD=yourpassword \
  tokpinch/tokpinch

Then add one line to your OpenClaw config:

ANTHROPIC_BASE_URL=http://localhost:4100/v1

Open http://localhost:4100/dashboard and watch your costs in real time.

Links:

GitHub: github.com/TobieTom/tokpinch
Landing page: tokpinch.vercel.app
Cloud version waitlist: tokpinch.vercel.app/#waitlist

If you're running OpenClaw or any AI agent with paid API access, give TokPinch a try. Star the repo if it's useful, and open an issue if you find bugs.

Built by TobieTom 🇳🇬

What features would you want to see next? Drop a comment below or open a GitHub issue.