From cardano-dev-skills
Diagnoses and fixes failing Cardano transactions by reading error messages, isolating failure layers, and dry-running the evaluator. Covers native script and Plutus script errors.
How this skill is triggered — by the user, by Claude, or both
Slash command
/cardano-dev-skills:debug-transactionThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!-- Documentation lookup path: ${CLAUDE_SKILL_DIR}/../../docs/sources/ -->
Guide the user through diagnosing and fixing failing Cardano transactions. Works with any SDK (Mesh, Evolution SDK, PyCardano, cardano-client-lib) and covers both native script and Plutus script errors.
build-transactionreview-contractoptimize-validatordesign-tokenRead the error message carefully. Cardano error messages are verbose but precise. They usually tell you exactly what is wrong. The error type name alone often identifies the problem.
Reproduce before fixing. Ensure you can consistently reproduce the error. Transaction failures are deterministic -- the same inputs and parameters will always produce the same result.
Isolate the failure layer. Determine if the error occurs during transaction building (SDK), during submission (node), or during script evaluation (Plutus VM).
Check the simple things first. Most transaction failures are caused by insufficient ADA, missing UTxOs, or wrong network. Check these before investigating complex script logic.
Use the transaction evaluator. Most SDKs support dry-run evaluation that simulates the transaction without submitting. Use this to test fixes before spending real resources.
Ask the user for:
Search the bundled documentation for relevant content:
${CLAUDE_SKILL_DIR}/../../docs/sources/evolution-sdk/ - Evolution SDK docs${CLAUDE_SKILL_DIR}/../../docs/sources/mesh-sdk/ - Mesh SDK docs${CLAUDE_SKILL_DIR}/../../docs/sources/cardano-node-wiki/ - Cardano node wikiClassify the error into one of these categories:
| Category | Common Errors | Likely Cause |
|---|---|---|
| Value errors | ValueNotConservedUTxO, OutputTooSmallUTxO | Math error in inputs/outputs, min-UTxO not met |
| Input errors | BadInputsUTxO | UTxO already spent or does not exist |
| Fee errors | FeeTooSmallUTxO | Fee calculation incorrect or overridden |
| Collateral errors | InsufficientCollateral, CollateralHasNonAdaAssets | Missing or wrong collateral for Plutus tx |
| Script errors | ScriptFailure, ExUnitsTooBigUTxO | Plutus script fails or exceeds budget |
| Datum errors | NonOutputSupplimentaryDatums | Datum provided but not referenced |
| Signer errors | MissingRequiredSigners | Required signature not included |
| Validity errors | OutsideValidityIntervalUTxO | Transaction time range does not match current slot |
Search ${CLAUDE_SKILL_DIR}/../../docs/sources/ or see references/common-errors.md for
detailed error explanations.
For each error category, follow these diagnostic steps:
evaluate_tx before submittingextra_signatoriesvalidity_range is tight
enough for the script's must_be_before / must_be_after checksOnce the root cause is identified:
Suggest practices to avoid the error in the future:
Most SDKs support evaluating a transaction without submitting:
evaluateTx endpointclient.newTx()...buildEither() for non-throwing inspection (result._tag === "Left" carries a tagged error). On Plutus failure, EvaluationError exposes failures[] with per-script purpose, label, validationError, and traces for trace-message-level debuggingcontext.evaluate_tx(tx)cardano-cli transaction evaluateLook up transaction hashes, UTxOs, and script addresses.
For inspecting raw transaction bytes:
cardano-cli transaction view --tx-file tx.signedWhen ExUnitsTooBigUTxO occurs:
optimize-validator)references/common-errors.md -- complete error reference with causes and fixes${CLAUDE_SKILL_DIR}/../../docs/sources/ for SDK-specific error handling guidesnpx claudepluginhub cardano-foundation/cardano-dev-skills --plugin cardano-dev-skillsProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.