---
title: "Error decoding"
description: "How OMS turns a custom program error or a failed transaction into a name and a message, and the order it looks in."
url: https://barestate.xyz/docs/concepts/error-decoding
---

# Error decoding

> How OMS turns a custom program error or a failed transaction into a name and a message, and the order it looks in.

A bare error code like `3012` or `0xbc4` tells you nothing until something maps it to a name. OMS does that in four layers, tried in order, so a code that an earlier layer knows never reaches the later ones.

### Offline error tables

A snapshot of pinned tables for Anchor framework errors (82 codes), System (9), SPL Token (20), Token-2022 (69) and Associated Token (1), which is 181 codes in all. OMS parses `3012`, `0xbc4` and `custom program error: 0x...` and matches by code, with aliases and program ids.

### Your project's own IDL

OMS reads errors from your IDL files in `target/idl/*.json`. It reads at most 16 files of up to 1,000,000 bytes each, and skips links that leave the worktree.

### Diagnosis of a failing command

If a failing command prints `InstructionError`, `Program ... failed:`, `AnchorError` or `custom program error`, OMS adds a short diagnosis of at most 2,048 bytes plus a raw tail. The diagnosis names the failed program, the error name, Anchor left and right values, the instruction, the account index mapped to the IDL account name, and compute units. The full log stays readable through the `raw_output` tool. For a landed transaction, OMS also adds lamport and owner changes from Surfpool.

### Documentation lookup

When no offline table or IDL knows the code, OMS asks its Solana reference service to decode it. Codes 6000 and above are program-defined.

## Use it

```text
/error <code> [program]
/tx <signature>
```

See [Decode an error](https://barestate.xyz/docs/guides/decode-an-error).

## Why it matters in benchmarks

On the `fresh-anchor-error-decode` task, which asks for an explanation of an Anchor failure from a bare transaction error without logs, the Codex CLI passed 0 of 12 runs and OMS passed 11 of 12, both with GPT-6.1 Sol. The benchmark pages treat this task separately for that reason. See [Fresh tasks](https://barestate.xyz/docs/benchmarks/fresh-tasks).