Reference/why_failed

Why did it fail?

$0.01per call after 25 free a day

Turns a Solana error (hex code, log line or RPC error) into the plain cause and fix. Offline, no chain call.

Run whenever a Solana transaction or dry run fails, before retrying. Retrying blind burns fees.

Saves money. Explains the failure before the agent retries. 0x1771 from Jupiter means the price moved past the slippage limit, and a blind retry won't fix that.

Call it

Transport	How
HTTP	`POST /api/tools/why_failed` with a JSON body of the inputs below.
MCP	`tools/call` with name `why_failed` on `/mcp`.

Inputs

Name	What it's looking for	Where to get it
`error` string or object, required	The error as you got it: "custom program error: 0x1771", "InsufficientFundsForRent", or the RPC error object.	From your send or RPC error, a dry-run result, a wallet message, or history.
`program` string (base58 address), optional	The failing program. Needed to read custom error codes right.	From the log line "Program <address> failed", or from explain_tx.

Returned fields

Every field the tool returns, what it is, and exactly how it's worked out.

Field	What it is	How it's worked out
`known` boolean	Whether we know this error.	At least one explanation matched.
`failed_step` number \| null	Which step in the transaction failed (counting from 0).	Read from InstructionError [step, ...] or "instruction N" in the text.
`program` string \| null	The program the error was read against.	Your input, or the program named in the error text.
`explanations[].name` string	The error's official name.	Matched against tables for transaction errors, instruction errors, the System and Token programs, Anchor and selected programs.
`explanations[].scope` string	Which layer raised it: transaction, instruction, system_program, token_program, anchor_framework or program_specific.	Which table matched.
`explanations[].meaning` string	What went wrong, in plain words.	Written by hand.
`explanations[].likely_cause` string	The usual reason it happens.	Written by hand.
`explanations[].fix` string	What to change before retrying, often naming the tool that helps.	Written by hand.
`next_step` string	The one thing to do next.	The first explanation's fix, or how to find the failing program when the error is unknown.

Limits

Custom codes 6000 and up are defined by each program. Without program we say so instead of guessing.