solerror

Decode Solana transaction errors into human-readable explanations with fix suggestions.

Takes a failed transaction signature, fetches it from RPC, parses the error, and returns a structured result with the error name, what it means, and how to fix it.

Install

npm install solerror

CLI

npx solerror <SIGNATURE>
npx solerror <SIGNATURE> --cluster devnet
npx solerror <SIGNATURE> --cluster https://my-rpc.com

Usage

Decode a failed transaction

import { decodeError } from "solerror";

const result = await decodeError(
  "5zSQuTcWsPy2cVAshBXWuJJXLwMD1GbgMpz3iq4xgwiV1s6mxYRbYb7qBiRGZd1xvDcYhQQRBKoNcnW8eKtcyZWg" as any,
  { url: "https://api.mainnet-beta.solana.com" },
);

console.log(result.error?.name); // "InsufficientFunds"
console.log(result.error?.explanation); // what went wrong
console.log(result.error?.fix); // how to fix it
console.log(result.error?.confidence); // "high" | "medium" | "low"

Resolve an error code directly

import { resolveError } from "solerror";

const entry = resolveError("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", {
  Custom: 1,
});

console.log(entry?.name); // "InsufficientFunds"

Register custom program errors

import { registerErrorMap } from "solerror";

const myProgramErrors = new Map([
  [
    0,
    {
      code: 0,
      name: "InvalidConfig",
      explanation: "Configuration is invalid",
      fix: "Check config parameters",
      confidence: "high",
    },
  ],
]);

registerErrorMap("MyProgram1111111111111111111111111111111", myProgramErrors);

Return type

interface DecodedError {
  signature: Signature;
  slot: bigint;
  instructionIndex: number | null;
  programId: Address | null;
  error: ErrorMapEntry | null; // decoded error details
  rawError: string | { Custom: number } | null;
  transactionError: string | null;
}

Supported Programs

Program	Error Codes
System Program	0–8
SPL Token	0–19
Token-2022	0–19 (shared with SPL Token)
Stake Program	0–15
Vote Program	0–19
Metaplex Token Metadata	0–202
Associated Token	— (uses Token Program errors)
Compute Budget	— (uses runtime InstructionError)

Plus 44 runtime instruction errors and 33 transaction errors.

API

decodeError(signature, rpcConfig, options?)

Fetches a failed transaction from RPC and decodes the error.

Parameters:

• signature — Transaction signature (88-char base58 string)
• rpcConfig — { url: string } RPC endpoint URL
• options? — { commitment?, maxSupportedTransactionVersion? }

resolveError(programId, rawError)

Looks up a custom error code in the built-in registry.

registerErrorMap(programId, errorMap)

Registers a custom error map for a program. Useful for Anchor-based programs with known error codes.

License

MIT