---
name: explain-evm-error
description: Explains an EVM transaction error and how to fix it, from the error pages on hashspan.dev, which list the exact messages that viem, wallets and JSON-RPC nodes print. Use when a transaction was rejected, reverted, ran out of gas, got stuck pending or was dropped and replaced, or when the user pastes an Ethereum error message such as "nonce too low" or "execution reverted".
license: Apache-2.0
---

# Explain an EVM transaction error

This skill only reads and explains. Never sign, send, speed up, replace or cancel a transaction, and never read
`.env` files, key files or secrets. When a fix needs a new transaction, write the code change and let the user run it.

## 1. Get the whole error

Ask for, or find in the logs, the full text: the message, the `Details:` line viem adds, the error class (such as
`NonceTooLowError` or `TransactionExecutionError`) and any JSON-RPC code. The short message alone often matches
several errors.

If the project traces with hashspan, read the trace too: a failed send records the error class viem classified as
`error.type` on the send span, and a mined transaction's confirm span records its status and the decoded revert
reason. Look up attribute names in https://hashspan.dev/docs/reference/semantic-conventions.md rather than guessing.

## 2. Match it to an error page

Fetch https://hashspan.dev/errors.md. Its table lists each error's message, the other wordings clients print for it
(viem's message, aliases and viem's error class), where the transaction stopped, the fix and the page. Match any of
these anywhere in the error text, ignoring hashes, addresses and numbers. When several match, the longest matching message wins.

If nothing matches, say so plainly and quote the message. Don't map it to the closest-sounding page. The user can
also paste it into the decoder at https://hashspan.dev/errors/decode.

## 3. Read the page before you answer

Fetch the matching page as Markdown (its URL in the table ends in `.md`). Use its sections:

- **Where does it stop?** Rejected before the chain means there is no transaction hash and nothing reached a block.
  Failed on the chain means the transaction was mined with a failed status. Waiting in the pool, or replaced in the
  pool, are the other two cases. Say which one this is first: it decides whether anything happened on chain.
- **Why does it happen?** Pick the cause that fits what the code does, such as a nonce set by hand or two workers
  sharing one account, and say why you picked it.
- **How do I fix it?** Apply the fix to this project's code.

## 4. Answer

Reply with:

1. What happened, in one sentence, and where it stopped.
2. The likely cause in this code, with the file and line.
3. The fix as a code change.
4. The link to the hashspan.dev page you used.

Don't state facts about fees, nonces or clients that the page or the code doesn't support. If the page doesn't cover
the user's client or chain, say that.