← All writing
·3 min read·solanatoolingresearchsithu nyein

Why Failed Solana Transactions Need a Diagnosis Layer

When a Solana transaction fails, the logs often show a code instead of a clear answer. I built an open diagnosis skill and a live explainer so you can paste a signature and get a readable cause and fix.

Most Solana tooling is built to help a transaction land. Retries, priority fees, and better RPC endpoints all help when you are still trying to send something. The harder problem I kept hitting was different: the transaction had already failed, the logs were crowded with noise, and I still did not know what to change next.

Program returned error: "custom program error: 0x1"
Transaction simulation failed: BlockHashNotFound
Instruction fell through

Those lines tell you that something went wrong. They do not tell you why it went wrong, or which field, account, seed, compute limit, or token amount you should fix. When you are shipping under a deadline, that gap costs real hours.

The loop I kept repeating by hand

Whenever I debug a failed Solana transaction myself, I end up doing the same sequence. First I fetch or simulate the transaction. Then I pull the program logs, error codes, compute usage, and account metadata. After that I try to map the code to the right family of errors, whether that is Anchor, SPL, System, or Token-2022. Only then can I make a serious guess about the root cause, which might be a CPI depth issue, a missing signer, a bad seed, a wrong account owner, or a compute unit limit that ran out too early. Finally I write a fix and hope the next simulation is cleaner.

That sequence is useful, but it is also repetitive. After enough nights of doing it for my own projects, I wanted a public tool that could carry the same recipe book for anyone who pastes a signature.

What I shipped

I published solana-tx-debugger-skill as an open Solana tooling skill, and I also shipped a browser product at solana-tx-explainer-ruby.vercel.app so you can paste a transaction signature and read a human diagnosis without setting up a local toolchain.

The skill walks through four jobs. It fetches the transaction and extracts the useful logs and metadata. It classifies known error codes against real Anchor, SPL, Token-2022, and System maps. It looks for a likely root cause from the logs, CPI path, compute budget, and accounts. Then it returns a concrete fix with a small runnable snippet instead of a vague suggestion to “try again.”

Accuracy matters more than sounding clever. User-defined Anchor errors start at 6000, and a wrong offset can send you into hours of pointless searching. Token-2022 transfer fees change amount math in ways that are easy to miss. Compute budget failures usually need both a higher limit and a better priority fee. The recipes encode those facts so the tool does not invent answers that only look confident.

Why this still matters in the products I ship

Most of my recent public work still depends on clean settlement paths. Vectra seals shift handoffs on Solana so the next plant team can verify what happened. Caixa settles shop payments in USDC on Solana without letting the bot hold keys. ShiftLedger batches payroll and leaves a receipt trail. When any of those paths fail, a vague retry loop is not enough. You need a readable diagnosis before you spend again or tell a user the job is done.

That is the research direction I care about. I want Solana failure modes to be easier to read. I want the recipes to stay verifiable against real transactions. And I want diagnosis to help recovery, not only late-night debugging.

What this is not

This is not a peer-reviewed paper. It is a public tooling artifact and a first-person note from me, Sithu Nyein. The claim is narrow: failed Solana transactions need a structured diagnosis layer, and that layer should be open, testable, and useful to both humans and the tools they run.

If you want the artifact, start here:

Sithu Nyein, Yangon