← all writing
·2 min read·solanaresearchtoolingsithu nyein

Why Failed Solana Transactions Need a Diagnosis Layer

Cryptic Solana errors waste hours. I built a diagnosis skill that maps Anchor, SPL, Token-2022, and compute failures to cause and fix. Notes from Sithu Nyein.

Most Solana tooling helps you land a transaction. Retries, priority fees, better RPCs. That is useful. It is not the hard part I kept hitting.

The hard part is this: the transaction already failed, the logs are noisy, and you still do not know what to change.

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

Those lines are not diagnoses. They are symptoms. If you are an agent, or a human shipping under a hackathon clock, symptoms are expensive.

The gap I kept seeing

When I debug Solana failures by hand, I do the same loop every time.

  1. Fetch or simulate the transaction.
  2. Pull program logs, error codes, compute usage, and account meta.
  3. Map the code to Anchor, SPL, System, or Token-2022 enums.
  4. Guess the root cause from CPI depth, signer flags, seeds, or CU limits.
  5. Write a fix and hope the next simulation is cleaner.

That loop is research-shaped work. It is also repetitive enough that an agent should be able to run it with a verified recipe book.

What I shipped

I published solana-tx-debugger-skill as a Solana AI Kit skill, plus a live browser demo at solana-explainer.vercel.app.

The skill does four things:

  • Triage: fetch the tx, extract logs and meta.
  • Classify: match codes against real Anchor / SPL / Token-2022 / System maps.
  • Diagnose: identify likely root cause from logs, CPI, compute, and accounts.
  • Prescribe: return a concrete fix with a runnable snippet.

The important detail is accuracy. User-defined Anchor errors start at 6000. Common wrong offsets waste time. Token-2022 transfer fees change amount math. Compute budget failures need both limit and priority fee changes. The recipes encode those facts so an agent does not invent them.

Why this matters for agents

I also build agents that spend money or settle outcomes on-chain. GoalTip signs tips locally. TxLINE Arena settles positions with SPL Memo hashes. NovaPay settles private payroll through Cloak shielded UTXOs.

If an agent cannot explain a failed transaction, it cannot recover safely. A vague retry loop is not a trust boundary. A diagnosis layer is.

That is the research direction I care about:

  • make Solana failure modes machine-readable
  • keep the recipes verifiable against real transactions
  • connect diagnosis to agent recovery, not only human debugging

What this is not

This is not a peer-reviewed paper. It is a public tooling artifact and a first-person research note from 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 agents.

If you want the artifact, start here:

Sithu Nyein, Yangon