How to decode a Solana custom program error (like 0x1771 or 3012)

Short answer

A Solana custom program error is a number the failing program chose, printed in hex. Convert it to decimal (0x1771 is 6001), find which program failed in the transaction logs, then look the number up in that program’s errors. For Anchor programs, codes from 6000 are your own enum in order, and lower codes are framework errors, such as 3012 (0xbc4) AccountNotInitialized.

Who it’s for
Solana developers staring at a failed transaction or test with a bare error code, and AI agents that need to explain one.
Last checked
, against Oh My Sol 0.1.0

What does a custom program error number mean?

A failed instruction often shows up in the logs like this:

Program <program id> failed: custom program error: 0x1771

Two facts are in that line, and you need both:

  • Which program failed. The number only has meaning inside that program. 0x1 from the SPL Token program is InsufficientFunds; 0x1 from the System program is ResultWithNegativeLamports.
  • The number, in hex. 0x1771 is 6001 in decimal, and 0xbc4 is 3012.

Native programs number their errors from 0 in the order of their error enum (see the SPL Token and System program source). Anchor programs use the ranges below.

How are Anchor error codes numbered?

From the ErrorCode enum in Anchor’s source:

RangeMeaning
100 and upInstruction errors, such as 100 InstructionMissing
1000 and upIDL instruction errors
2000 and upConstraint errors, such as 2006 ConstraintSeeds
3000 and upAccount errors, such as 3012 AccountNotInitialized
4100 and upMiscellaneous errors, such as 4100 DeclaredProgramIdMismatch
5000Deprecated API
6000 and upYour program’s own errors (ERROR_CODE_OFFSET = 6000), numbered in enum order

Common codes:

DecimalHexNameMessage
20030x7d3ConstraintRawA raw constraint was violated
20060x7d6ConstraintSeedsA seeds constraint was violated
30070xbbfAccountOwnedByWrongProgramThe given account is owned by a different program than expected
30120xbc4AccountNotInitializedThe program expected this account to be already initialized
60000x1770First variant of your #[error_code] enumDefined by your program
60010x1771Second variant of your #[error_code] enumDefined by your program

An #[error_code(offset = N)] attribute moves your program’s errors to start at N instead of 6000. The Anchor errors guide covers defining them.

How do I decode an error by hand?

  1. Get the logs. In a test, they are usually in the error output. For a landed transaction:
    solana confirm -v <signature>
  2. Find the line that says which program failed.
  3. Convert the hex code:
    printf '%d\n' 0x1771    # 6001
  4. If the program is yours and built with Anchor, look the code up in the IDL:
    jq '.errors[] | select(.code == 6001)' target/idl/my_program.json
  5. If it is an Anchor framework code (below 6000), use the table above. If it is a native or SPL program, read that program’s error enum.

When an AI agent does this for you, give it the logs and the IDL, not just the code, so it can name the program and the variant from the source.

How do I decode an error in Oh My Sol?

Inside Oh My Sol (OMS), one command does the lookup, with no model turn:

/error 3012
/error 0xbc4
/error <code> <program>
/tx <signature>

/error accepts a decimal code, a hex code, or the text custom program error: 0x..., and a program name or id narrows the match. It looks in four places, in order:

  1. Offline tables: Anchor framework (82 codes), System (9), SPL Token (20), Token-2022 (69) and Associated Token (1), 181 codes in all.
  2. Your project’s IDL files in target/idl/*.json, which name your 6000-and-up errors.
  3. When a command fails inside a session and prints InstructionError, AnchorError or custom program error, a short diagnosis: the failed program, the error name, the instruction, the account name from the IDL and the compute units.
  4. Its Solana reference service, when nothing earlier knows the code.

/tx shows the status, error, compute units and logs for a transaction on the local Surfpool chain. For codes 6000 and up, OMS reads the names from your IDL, so run anchor build first if target/idl is missing.

In the benchmark’s error-decoding task, which asks for an explanation of an Anchor failure from a bare transaction error, OMS with GPT-6.1 Sol passed 11 of 12 runs and Codex CLI passed none.

Frequently asked questions

What does "custom program error: 0x1771" mean?

The program that failed returned its own error number, printed in hex. 0x1771 is 6001 in decimal. In an Anchor program, user-defined errors start at 6000, so 6001 is the second variant in the program’s #[error_code] enum. Look it up in the program’s IDL to get the name and message.

What is Anchor error 3012?

3012 (0xbc4) is AccountNotInitialized: "The program expected this account to be already initialized". It usually means an account passed to the instruction has not been created yet, or the wrong address was passed.

Why does the same error number mean different things?

Custom error numbers are defined by each program. 0x1 from the SPL Token program is InsufficientFunds, while 0x1 from the System program is ResultWithNegativeLamports. Always read which program failed in the transaction logs before you look the number up.

Where do I find the error names for my own Anchor program?

In the IDL that anchor build writes to target/idl/<program>.json. Its errors list gives each code, name and message. You can also read the #[error_code] enum in your program source and count from 6000, unless the enum sets a different offset.

How does Oh My Sol decode Solana errors?

Type /error 3012, /error 0xbc4 or /error <code> <program> inside Oh My Sol (OMS). It checks offline tables for 181 Anchor, System, SPL Token, Token-2022 and Associated Token codes, then your project’s IDL files, then its Solana reference service. /tx <signature> shows the status, error, compute units and logs of a transaction on the local chain. Neither command uses a model turn.

Try it on your own program

Oh My Sol 0.1.0 runs on macOS and Linux, and on Windows through WSL 2. You need Node 22.19.0 or newer and Git. You bring your own model access: an API key, a ChatGPT subscription or a Claude subscription.

npx @barestate/oms doctor --install
npx @barestate/oms