diagnose-errors

Diagnose before guessing

cardano-mcp tool errors carry real, specific information — an HTTP status from Blockfrost/Koios/Maestro/Kupo, a CBOR/PlutusData deserialization message, or (for submit_transaction) the Cardano ledger's own rejection reason. That's much more useful than it looks at first glance, but only if it's actually read rather than treated as an opaque failure to retry or apologize for.

Workflow

1. When a cardano-mcp tool call returns isError: true, or a contracts module tool returns status: "error", read ${CLAUDE_PLUGIN_ROOT}/reference/error-catalog.md before proposing a fix or retrying.
2. Match the error text against the catalog: which client produced it (Blockfrost/Koios/Maestro/Kupo/CBOR/ledger-rejection), what the status/message actually means, and the catalog's suggested fix.
3. Explain the real cause to the user in those terms — "Blockfrost returned 403, which means the project ID doesn't match the configured network" beats "something went wrong, let me try again."
4. If the error doesn't match anything in the catalog, say so explicitly and reason from the raw message rather than pattern-matching it to the closest catalog entry that doesn't quite fit.
5. For submit_transaction specifically: never resubmit the same signed CBOR after a ledger rejection. The catalog's fixes are all "rebuild the transaction" (fresh UTxOs, fresh TTL, corrected fee) — a rejected transaction's problem doesn't go away by retrying the exact same bytes.

Why this exists

An agent's first instinct on a tool error is often to guess — "maybe the network is down, let me retry" — when the error text already states the real cause precisely (a 403 from Blockfrost, a BadInputsUTxO ledger rejection). Consulting a known catalog of what this server's own errors actually mean, the same way aiken-verify consults the real compiler instead of guessing whether code compiles, turns a vague "it failed" into a correct, specific diagnosis.