tx-doctor

name

tx-doctor

description

Explain why an Ethereum, Base, Arbitrum, Optimism or Polygon transaction failed. One-shot. Use when the user pastes a transaction hash and asks what went wrong, says a transaction failed or reverted, asks why a swap, approval, mint, claim or bridge did not work, asks what "execution reverted" or a bare 0x error selector means, or asks whether a failure was their fault. Also use when a user reports losing gas on a transaction that did nothing. Do NOT use for transactions that are still pending and have no receipt, for questions about what a transaction did when it succeeded, or for general contract auditing.

tx-doctor

A receipt says a transaction failed. It does not say why — revert data is not stored on chain. This recovers it by replaying the call against the state of the block it ran in, then names the cause.

Procedure

1. Run node bin/tx-doctor.mjs <hash> --json. Add --chain <name> when the user named a chain other than Ethereum; if they named none, run Ethereum and state that assumption in your answer.
2. Read diagnosis.cause and diagnosis.confidence from the JSON. Form your answer from those fields. Do not read the raw revert string and reach your own conclusion.
3. Open with diagnosis.title rephrased in the user's own terms. Put no hex, no selector and no gas figure in the first sentence.
4. State what the transaction was attempting, using attempted.signature. When attempted.signature is absent, write that the function could not be identified — do not infer it from the recipient address or the user's story.
5. Give at most three items from diagnosis.fixes, choosing the ones that fit what the user described. Do not invent a fix that is not in the array.
6. When confidence is low, write that the reason could not be recovered and name what would recover it (an archive-capable RPC endpoint). Do not present a low-confidence cause as the answer.
7. When cause is ordering-dependent, tell the user their inputs were valid and they lost a race. Do not tell them to change parameters.
8. When cause is contract-panic and panicCode is not 0x11 or 0x12, tell the user there is nothing they can change and name the protocol as the party to report it to.
9. When cause is out-of-gas, state that the gas was still charged.

What each cause means for the reader

cause	Whose problem it is	Lead with
slippage	The market moved	The protection worked; retry with a fresh quote
insufficient-allowance	Caller's setup	Approve the spender, then retry
insufficient-balance	Caller's funds	The balance at execution time, not now
deadline-expired	Transaction was too slow	It sat in the mempool; resubmit with a higher fee
access-control	Wrong sender	Which address is permitted
paused	Protocol admin	Nothing to fix; wait
reentrancy	Token or routing	A callback token tripped a guard
ordering-dependent	Nobody's input	They lost a race, not a validation
out-of-gas	Caller's limit	Raise the limit; the gas was still charged
contract-panic	Usually the contract	A broken invariant, not rejected input
custom-error-unknown	Unrecoverable name	The selector cannot be reversed; the ABI would name it
silent-revert	Ambiguous	Often the wrong chain or an address with no code
unknown	Not recovered	Say so, and name the endpoint that would answer

Never

• Never tell the user to check Etherscan for the reason. You have the reason.
• Never construct, sign, or send a replacement transaction.
• Never advise raising slippage further than diagnosis.fixes already does; the array's own caution about sandwiching is part of the answer.
• Never state a cause the tool did not report.

Example

Instead of:

Your transaction reverted with 0x08c379a0.... This usually means a require statement failed. You could try checking on Etherscan for more details, or increasing your gas limit and slippage to see if that helps.

Do:

The price moved past your slippage tolerance, so the swap was rejected rather than filled at a worse price — the protection did its job. You were calling swapExactTokensForTokens, and it used 12% of its gas limit, so gas was not the issue. Confidence: high.

Retry with a fresh quote. If it keeps failing on a thin pool, splitting into smaller trades reduces impact — widening slippage a long way is what makes sandwiching you profitable.

Observable effect

Every answer names a cause and a confidence level taken from the tool's JSON, and contains no cause the tool did not report. The phrase "check Etherscan" does not appear.

Deeper detail

Load only when the specific question calls for it:

• references/failure-modes.md — how each cause is detected, and where the detection is wrong
• references/recovering-revert-data.md — why revert reasons are not on chain, and what the replay actually does