---
title: "How to decode a Solana custom program error (like 0x1771 or 3012) · Barestate"
description: "What 'custom program error: 0x...' means on Solana, how to convert it and match it to the right program, Anchor's error code ranges, and how to decode errors with one command in Oh My Sol."
url: https://barestate.xyz/solana/decode-solana-custom-program-errors
---

# 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

November 16, 2026, 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](https://github.com/solana-program/token) and [System](https://github.com/solana-program/system) program source). Anchor programs use the ranges below.

## How are Anchor error codes numbered?

From the `ErrorCode` enum in [Anchor’s source](https://github.com/solana-foundation/anchor/blob/master/lang/src/error.rs):

| Range | Meaning |
| --- | --- |
| 100 and up | Instruction errors, such as 100 InstructionMissing |
| 1000 and up | IDL instruction errors |
| 2000 and up | Constraint errors, such as 2006 ConstraintSeeds |
| 3000 and up | Account errors, such as 3012 AccountNotInitialized |
| 4100 and up | Miscellaneous errors, such as 4100 DeclaredProgramIdMismatch |
| 5000 | Deprecated API |
| 6000 and up | Your program’s own errors (`ERROR_CODE_OFFSET = 6000`), numbered in enum order |

Common codes:

| Decimal | Hex | Name | Message |
| --- | --- | --- | --- |
| 2003 | `0x7d3` | ConstraintRaw | A raw constraint was violated |
| 2006 | `0x7d6` | ConstraintSeeds | A seeds constraint was violated |
| 3007 | `0xbbf` | AccountOwnedByWrongProgram | The given account is owned by a different program than expected |
| 3012 | `0xbc4` | AccountNotInitialized | The program expected this account to be already initialized |
| 6000 | `0x1770` | First variant of your #[error_code] enum | Defined by your program |
| 6001 | `0x1771` | Second variant of your #[error_code] enum | Defined 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](https://www.anchor-lang.com/docs/features/errors) 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
```

[Read the docs](https://barestate.xyz/docs) · [See the benchmarks](https://barestate.xyz/oh-my-sol#benchmarks)
