---
title: "How to debug a failed Solana transaction with AI · Barestate"
description: "Debug a failed Solana transaction: get the program logs, decode custom program errors and Anchor error codes, check compute units, and let an AI agent help without guessing. Includes Oh My Sol’s /tx and /error."
url: https://barestate.xyz/solana/debug-a-failed-solana-transaction-with-ai
---

# How to debug a failed Solana transaction with AI

Short answer

Get the full program logs first, not just the error line: solana confirm -v <signature>, Solana Explorer, or simulateTransaction before you send. Find the program that logged “failed”, convert its custom error code from hex, and look it up in that program’s error table or your IDL. Give the AI the logs and the IDL. In Oh My Sol, /tx shows a local transaction’s logs and compute, and /error decodes the code offline.

Who it’s for

Solana developers looking at a failed transaction, a hex error code or an exceeded compute meter, who want an AI agent to help find the cause instead of guessing.

Last checked

November 16, 2026, against Oh My Sol 0.1.0

## How do I get the logs for a failed transaction?

The error line alone (“custom program error: 0x…”) rarely tells you which instruction or account failed. The program logs do. Get them one of three ways:

```
# A landed transaction, from the CLI
solana confirm -v <SIGNATURE> --url <cluster>

# Stream msg!() output from programs on a local validator
solana logs --url localhost
```

- **Solana Explorer:** paste the signature, with the cluster set to where it ran.
- **Before sending:** [`simulateTransaction`](https://solana.com/docs/rpc/http/simulatetransaction) runs a signed transaction against current chain data without broadcasting it and returns the error, the logs and the compute units consumed.

In the logs, find the line where a program reports `failed`. The error belongs to that program, which matters: a low code like `0x1` means different things in different programs.

## How do I read the error code?

Convert the hex code to decimal, then look it up in the failing program’s error table. For Anchor programs the ranges are fixed:

| Range | Meaning | Example |
| --- | --- | --- |
| 100+ | Instruction errors | 100 InstructionMissing |
| 1000+ | IDL instruction errors | 1000 IdlInstructionStub |
| 2000+ | Constraint violations | 2006 (0x7d6) ConstraintSeeds |
| 3000+ | Account errors | 3012 (0xbc4) AccountNotInitialized |
| 6000+ | Errors your program defines, in `#[error_code]` order | 6001 (0x1771) is the second variant |

Source: the `ErrorCode` enum and `ERROR_CODE_OFFSET = 6000` in [Anchor’s source](https://github.com/solana-foundation/anchor/blob/master/lang/src/error.rs). Your own errors are listed by code in `target/idl/<program>.json` after `anchor build`. The [custom program errors guide](https://barestate.xyz/solana/decode-solana-custom-program-errors) covers SPL Token, Token-2022 and System program codes too.

## What if it ran out of compute units?

Each instruction gets 200,000 compute units by default, and a transaction can request at most 1,400,000 ([Solana fees and compute budget](https://solana.com/docs/core/fees)). If the logs show the meter running out, add a `SetComputeUnitLimit` instruction from the Compute Budget program with a higher limit, or cut the work: fewer accounts deserialized, less logging, smaller loops. Simulation reports `unitsConsumed`, which is a good starting point for the limit.

## How do I get an AI agent to debug it well?

1. Give it the **full logs**, not just the error string. Without logs, a model has to guess which program and instruction failed.
2. Give it the **IDL** (`target/idl/*.json`) so it can map a custom code and an account index to names.
3. Ask it to name the failing program, instruction, error and account **before** it changes code.
4. Have it **reproduce the failure locally** in a test (LiteSVM or a local validator), fix it, and show the test passing.
5. Check its decoding against the program’s own error table or IDL, not a table it recalls.

## How does Oh My Sol help debug a failure?

Oh My Sol (OMS) has two commands for this. Both work without a model turn, including while the agent is running:

```
/tx <signature>        # status, error, compute units and logs, on the local Surfpool chain
/error 3012
/error 0xbc4
/error <code> <program> # narrow the match to one program
```

`/error` accepts decimal, hex and the text `custom program error: 0x…`. It looks in three places, in order: offline tables for Anchor (82 codes), System (9), SPL Token (20), Token-2022 (69) and Associated Token (1); your project’s IDLs under `target/idl`; and only then the Solana reference service.

When a command the agent runs prints `InstructionError`, `Program … failed:`, `AnchorError` or `custom program error`, OMS adds a short diagnosis to the output: the failed program, the error name, Anchor’s left and right values, the instruction, the account index mapped to the IDL account name, and compute units. For a landed transaction it also adds lamport and owner changes from the local chain. The full log stays available to the model through its `raw_output` tool.

OMS can name codes 6000 and above from your project’s IDLs or its reference service, since each program defines its own. `/tx` reads the local chain, so for a failure on a public cluster, take the logs from Explorer or `solana confirm -v` and reproduce it in a local test.

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

How do I see why a Solana transaction failed?

Read its program logs. From the CLI, solana confirm -v <SIGNATURE> prints the transaction in detail, including the logs; Solana Explorer shows the same for a signature on the right cluster. Before sending, simulateTransaction returns the error, the logs and the compute units consumed without broadcasting anything.

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

0x1771 is 6001 in decimal. In an Anchor program, codes from 6000 up are the program’s own errors, numbered in the order of its #[error_code] enum, so 6001 is the second variant. The program’s IDL in target/idl lists them by code.

What do Anchor error codes like 2006 or 3012 mean?

Anchor framework errors are grouped by range: 100 and up for instructions, 1000 for the IDL, 2000 for constraints, 3000 for accounts, and 6000 and up for errors your program defines. 2006 (0x7d6) is ConstraintSeeds, "A seeds constraint was violated". 3012 (0xbc4) is AccountNotInitialized, "The program expected this account to be already initialized".

Why did my transaction run out of compute units?

Each instruction gets 200,000 compute units by default and a transaction can request at most 1,400,000. If the logs show the meter running out, request a higher limit with the Compute Budget program’s SetComputeUnitLimit instruction, or reduce the work the instruction does.

Can Oh My Sol read a mainnet or devnet transaction?

/tx reads transactions on the local Surfpool chain that Oh My Sol (OMS) runs. For a mainnet or devnet failure, get the logs with solana confirm -v or Explorer, decode the code with /error, and reproduce the failure locally with the accounts set up in a test.

## 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)
