Debugging Failed Transactions

Failed Solana transactions leave clues in simulation logs, RPC error codes, and explorer program output. A disciplined decode workflow separates user errors, client bugs, RPC issues, and on-chain program defects before you retry or page on-call.

Recipe

Quick-reference recipe card - copy-paste ready.

import { createSolanaRpc } from "@solana/kit";
 
const rpc = createSolanaRpc(process.env.RPC_URL!);
 
const sim = await rpc
  .simulateTransaction(base64Tx, {
    sigVerify: false,
    replaceRecentBlockhash: true,
    commitment: "confirmed",
  })
  .send();
 
if (sim.value.err) {
  console.error("err:", sim.value.err);
  console.error("logs:", sim.value.logs?.join("\n"));
  console.error("units:", sim.value.unitsConsumed);
}

When to reach for this:

• A user reports "transaction failed" with only a signature
• Preflight rejects before the tx hits the network
• Program returns Custom: N and you need the enum mapping
• Compute or account size errors spike after a deploy
• Incident triage needs error class before paging program owners

Working Example

import {
  createSolanaRpc,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  signTransactionMessageWithSigners,
  getBase64EncodedWireTransaction,
  pipe,
} from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
 
async function debugTransfer(signer: Awaited<ReturnType<typeof import("@solana/kit").createKeyPairSignerFromBytes>>) {
  const { value: blockhash } = await rpc.getLatestBlockhash().send();
 
  const message = pipe(
    createTransactionMessage({ version: 0 }),
    (m) => setTransactionMessageFeePayer(signer.address, m),
    (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
    (m) =>
      appendTransactionMessageInstruction(
        getTransferSolInstruction({
          source: signer,
          destination: signer.address,
          amount: 1n,
        }),
        m,
      ),
  );
 
  const signed = await signTransactionMessageWithSigners(message);
  const wire = getBase64EncodedWireTransaction(signed);
 
  const sim = await rpc
    .simulateTransaction(wire, {
      sigVerify: true,
      replaceRecentBlockhash: false,
      commitment: "confirmed",
    })
    .send();
 
  return {
    err: sim.value.err,
    logs: sim.value.logs ?? [],
    unitsConsumed: sim.value.unitsConsumed,
    accounts: sim.value.accounts,
  };
}

What this demonstrates:

• Building a real transaction and simulating with replaceRecentBlockhash off when testing signature validity
• Reading err, logs, and unitsConsumed as the primary debug triple
• Using @solana/kit 7.0.0 RPC types for typed simulation responses
• Capturing account post-simulation state when debugging rent or owner mismatches

Deep Dive

How It Works

• Preflight simulation runs the transaction against current ledger state before broadcast (when enabled on sendTransaction).
• Program logs emit via sol_log / msg! / anchor_lang::prelude::* and appear in simulation and confirmed transaction metadata.
• Custom program errors encode as InstructionError::Custom(u32) - map to your IDL or #[error_code] enum.
• Compute budget defaults to 200,000 CUs per instruction unless you prepend ComputeBudget instructions.
• Account meta mismatches fail before execution: wrong signer flag, wrong writable flag, or missing account.

Error Classes at a Glance

TypeScript Notes

function parseCustomError(logs: string[]): number | null {
  const line = logs.find((l) => l.includes("custom program error:"));
  if (!line) return null;
  const m = line.match(/custom program error: (0x[0-9a-f]+|\d+)/i);
  if (!m) return null;
  return m[1].startsWith("0x") ? parseInt(m[1], 16) : Number(m[1]);
}

Rust / Anchor Notes

// Anchor 0.32.1 - errors surface as Custom codes in logs
#[error_code]
pub enum MyError {
    #[msg("Vault is paused")]
    VaultPaused,
}
// Map: anchor error --program-id <PID> shows code -> name

Gotchas

• Retrying without reading logs - Users hammer resubmit; you burn priority fees on the same deterministic failure. Fix: Simulate once, classify error, fix root cause.
• Wrong cluster RPC - Devnet tx simulated against mainnet RPC returns AccountNotFound. Fix: Pin RPC_URL, wallet network, and explorer ?cluster= together.
• Assuming preflight is always on - Some server paths disable preflight for latency. Fix: Explicit simulateTransaction in support tooling.
• Decimal vs lamport amounts - Client sends 1.5 SOL as float; program expects integer lamports. Fix: bigint end-to-end; convert at UI boundary only.
• Stale IDL error map - Deployed program v2, client still decodes v1 codes. Fix: Version IDL in CI; regenerate clients on every program release.
• Ignoring unitsConsumed - Near-limit programs fail only under load. Fix: Track CU in metrics; alert when p95 exceeds 80% of budget.

Alternatives

FAQs

Related

• Transactions Not Landing - when simulation passes but inclusion fails
• RPC & Infrastructure Outages - provider-side failures
• Prevention Checklists - monitors and alerts after incidents

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.