Troubleshooting

Common Errors and Troubleshooting.

When building on the Anvil API (Cardano), you may encounter various errors related to transaction submission, UTXOs, API components, or authorization. This page documents common error messages, explains their causes (Cardano-specific vs Anvil-specific), and provides solutions or workarounds for each.

Transaction Submission Failures

These errors occur when a transaction fails Cardano's validation rules during building or submission. They are typically Cardano-specific (originating from the Cardano node/ledger) but can surface through the Anvil API's responses.

Missing Required Signatures (MissingVKeyWitnessesUTXOW)

What it means: The node is telling you that one or more required transaction signatures (vkey witnesses) are missing. The error MissingVKeyWitnessesUTXOW appears when the transaction hasn't been signed by all the necessary keys needed to validate the transaction.

Cardano or Anvil: Cardano-specific (signature validation failure). Anvil passes along the node's error.

Solution:

  1. Include all signatures: Ensure all required signatures are present in the transaction:

    • For ADA spending: Include the address's payment signing key

    • For minting/burning: Include the policy script's key (minting/burning tokens specifically requires the policy signature)

    • For script interactions: Include any required script witnesses

  2. Complete frontend signing: When building via API and signing on frontend, verify the signed payload contains all required signatures

Transaction Validity Interval Error (OutsideValidityIntervalUTxO)

What it means: The transaction's validity interval is outside the current blockchain slot range. This error indicates that the transaction is either expired (current slot > end slot/TTL) or not yet valid (current slot < start slot).

Cardano or Anvil: Cardano-specific (timing validation).

API Details:

  • In Anvil's API, you can specify the validity interval using the validityInterval parameter:

    {
  "validityInterval": {
    "start": number | false, // POSIX timestamp or slot number (optional)
    "end": number | false   // POSIX timestamp or slot number (optional)
  }
}

  • Default values (when not specified):

    • start: Current blockchain slot (from chain indexer)

    • end: Current blockchain slot + 2 hours (from chain indexer)

  • Set a boundary to false to disable it entirely

Common scenarios:

  • Transaction submitted after its TTL has expired

  • Transaction submitted before its start time is reached

  • Clock differences between systems

  • Chain indexer issues causing incorrect validity interval calculations

Solution:

  1. Explicitly set validity interval: Instead of relying on defaults, specify both start and end:

    • For immediate transactions: Set start to a recent slot and end to at least 30 minutes in the future

    • For scheduled transactions: Set appropriate future start time and ensure end provides enough window

  2. Use relative values: Calculate values relative to current time rather than using absolute slots

  3. Chain indexer issues: If you've verified your validity interval is correct but still get this error, the chain indexer may be out of sync. In this case contact Anvil support if the issue persists

Note on terminology: Cardano error messages use invalidBefore (= Anvil's start) and invalidHereafter (= Anvil's end).

Smart Contract Script Failure (Validation Error 3010/3012)

What it means: Your smart contract returned False during validation or encountered an execution error. Errors typically appear with codes 3010 ("Some scripts of the transaction terminated with errors") or 3012 ("Some scripts failed to evaluate to a positive outcome").

Cardano or Anvil: Cardano-specific (on-chain script validation).

Common causes:

  • Contract logic rejected the transaction parameters

  • Incorrect datum or redeemer values

  • Missing required inputs or signatures

  • Execution units exceeded

Solution:

  1. Review error traces: The data.validationError and data.traces fields contain valuable debugging information

  2. For Aiken contracts: Rebuild your contract with verbose mode to get detailed execution traces:

    aiken build --verbose

  3. Check parameters: Verify all datum values, redeemers, and required signatures

This error is specific to your smart contract's logic - the solution depends entirely on the contract code and the validation conditions it requires.

Malformed Transaction Submission (Raw CBOR Decode Error)

What it means: The node cannot decode your transaction because the CBOR format is incorrect. Error messages include "DecoderErrorDeserialiseFailure" or "RawCborDecodeError".

Cardano or Anvil: Cardano error (node-level validation).

Common causes:

  1. Incorrect encoding: Transaction must be CBOR Hex Encoded

  2. Missing signatures: Incomplete transaction witness data

  3. Improper signing workflow: Incorrect signature appending

Solution:

  1. Use proper encoding: When submitting via REST, ensure you're using CBOR Hex Encoded format

  2. Verify complete signatures: Make sure all required signatures are included

  3. Follow correct signing flow: When using Anvil's API where the backend returns an unsigned tx hash to be signed by the frontend, append signatures only in the designated witness fields

UTXO/Input Issues

Errors in this category relate to UTXOs (Unspent Transaction Outputs) and inputs selection for your transactions. They might be Cardano errors triggered by incorrect input usage or Anvil-specific validations about how inputs are provided.

Insufficient Inputs (Balance Shortage)

What it means: Your transaction inputs don't have enough value to cover all outputs and fees. The error typically shows: "Insufficient input in transaction. shortage: {ada in inputs: X, ada in outputs: Y, fee: Z}".

Key requirement: The rule "ada in inputs" must be >= ("ada in outputs" + fee) before adding change.

Cardano or Anvil: Cardano-specific (transaction balancing).

Common causes:

  • Insufficient ADA for outputs, fees, and minimum deposit requirements

  • Missing tokens you're trying to send

  • Wrong network (using testnet addresses when on mainnet or vice versa)

Solution:

  1. Add more inputs: Include additional UTXOs from your wallet

  2. Check token presence: Verify the UTXO contains the specific tokens (NFTs, FTs, and/or ADA) you're sending

  3. Verify network: Ensure you're using addresses on the correct network

This error can apply to both ADA and native assets (NFTs and tokens).

Using a Spent or Invalid UTXO (BadInputsUTxO / ValueNotConservedUTxO)

What it means: This error combo occurs when one of the UTXO inputs you included is not actually available to spend. BadInputsUTxO means the transaction is referencing an input that the ledger finds invalid – typically because it's already spent (or doesn't exist).

Cardano or Anvil: Cardano-specific (UTXO set validation). Anvil just surfaces it.

Solution:

  1. Check UTXO status: If you recently used a UTXO in a transaction, consider it already spent

  2. Refresh your wallet: Always fetch the latest UTXOs from the address by refreshing your wallet before building a new transaction

  3. Use different UTXOs: For multiple back-to-back transactions, use separate UTXOs for each transaction

  4. Inspect error details: If the error persists, check the specific TxIn hash mentioned in the error message

UTXO Fragmentation (UtxoNotEnoughFragmented / "Wallet fragmentation error")

What it means: "Wallet fragmentation" refers to the distribution of funds across UTXOs. An error like UtxoNotEnoughFragmented means you don't have enough separate UTXOs to fulfill all the outputs you are trying to create.

Cardano or Anvil: This is more of a higher-level Cardano wallet limitation/feature.

Solution:

  1. Consolidate and re-split: If your funds are in a single UTXO, first create a transaction to split it into multiple smaller UTXOs

  2. Reduce batch size: Break large multi-recipient transactions into smaller batches with fewer outputs

  3. Check UTXO count: Use wallet tools to verify your UTXO count matches your transaction requirements

  4. Verify balance: Ensure you have sufficient funds available if the error is actually related to balance

Providing UTXOs vs. Using an Address (Blockfrost "Component not found")

What it means: No UTXOs found for the provided address. The error appears as "The requested component has not been found" with internal code -32603 or HTTP status 500 from Blockfrost.

Cardano or Anvil: Blockfrost response error when querying address UTXOs.

Address format support:

  • Anvil API supports both bech32 addresses (addr1...) and hex-encoded addresses

  • The address must be valid and properly formatted

Solution:

  1. Fund the address first: Ensure the address has received at least one transaction

  2. Use explicit UTXOs:

    • Frontend: Connect through wallet interfaces (e.g., Weld) to access UTXOs directly from the user's wallet

    • Backend: Fetch UTXOs using Blockfrost or other Cardano service providers and provide them in the utxos field of your build request

    • Note: Backend UTXO handling for your address may vary based on wallet settings (e.g., Eternl multi-account configuration)

    See Selecting UTXOs for more detailed information.

  3. Verify address format: Double-check that you're using a valid bech32 or hex-encoded address format

This error simply means there are no UTXOs associated with the address you provided.

Mainnet UTXO Selection Requirement ("Utxos must be set on mainnet")

What it means: This is an Anvil API validation error (HTTP 400) that explicitly requires you to provide UTXO inputs in the request when operating on mainnet. The error message Input validation failed ... "Utxos must be set on mainnet" is telling you that unlike test environments, the mainnet API will not automatically pick UTXOs for you.

Cardano or Anvil: Anvil-specific. This is not coming from Cardano node, but from Anvil's API input checker.

Solution:

  1. Retrieve UTXOs: First, fetch the UTXOs for the wallet address you want to spend from

  2. Include UTXOs in request: Add the utxos field to your build transaction request, listing each UTXO you want to use as input. See Selecting UTXOs for more details.

  3. Verify network: Confirm you're correctly pointing to mainnet

This requirement exists to ensure developers make deliberate decisions about which UTXOs to spend when operating on mainnet.

Policy Script Hash Mismatch (UNPROCESSABLE_CONTENT)

What it means: The error message "Failed to build transaction > Unable to get policy scripts > Policy script and policy id do not match" indicates that the native script content doesn't match the policy ID hash being used.

Cardano or Anvil: This is primarily a Cardano validation error that Anvil surfaces.

Common causes:

  • The native script JSON in the preloaded script section was altered but the policy ID wasn't updated accordingly

  • The policy ID was manually entered or calculated incorrectly

  • Using the wrong script version for a specific policy ID

Solution:

  1. Verify script content: The native script (the json in the preloaded script section) is different from the hash being used. You should double check that you didn't alter the native script and generate a new hash if necessary.

  2. Regenerate hash if needed: If you intentionally modified the script, you need to regenerate the hash to match.

  3. Use consistent script: Ensure you're using exactly the same script content throughout your application.

Invalid Address Format (ScriptWitnessNotValidatingUTXOW)

What it means: When you see a transaction submission error containing "ConwayUtxoValidationError" and "ScriptWitnessNotValidatingUTXOW" followed by "missing human-readable separator", it typically indicates an invalid address format is being used. The error message appears as: "Failed to submit tx > {"contents":{"contents":{"era":"ShelleyBasedEraConway","error":{"ConwayUtxoValidationError (ScriptWitnessNotValidatingUTXOW ...", code: "UNPROCESSABLE_CONTENT", error: 'missing human-readable separator, "!"'

Cardano or Anvil: This is a Cardano validation error related to address format checking.

Common causes:

  • Using a malformed address that's neither a valid hex-encoded nor bech32 format

  • Truncated or corrupted address strings

  • Mixing address formats from different networks (testnets vs mainnet)

Solution:

  1. Validate address format: Ensure all addresses in your transaction are either valid bech32 format (starting with addr1..., addr_test1..., etc.) or properly hex-encoded

  2. Check for truncation: Verify that addresses haven't been truncated during processing

  3. Use network-appropriate addresses: Confirm you're using addresses appropriate for the network you're targeting (mainnet vs testnet)

Component or Endpoint Errors

These errors are related to specific components of the Anvil platform or external endpoints it relies on (like Blockfrost).

External Data Not Yet Available (Policy Script/CBOR Not Found)

What it means: This error occurs when Anvil tries to retrieve on-chain data that hasn't settled yet. The error message typically looks like: "Unable to get policy scripts > Failed to get cbor for tx hash > The requested component has not been found" with code 422.

Cardano or Anvil: This is a timing issue related to blockchain confirmation times.

Common causes:

  1. Transaction not yet settled: The transaction containing the policy script hasn't been fully confirmed

Solution:

  1. Wait for on-chain settlement: Allow more time for the transaction to be confirmed before trying to use its data

  2. Implement retry logic: If building an application, add a delay and retry mechanism

  3. Check network: Verify you're looking for the transaction on the same network where it was submitted

Authorization/Access Issues

These errors relate to authentication (API keys) or account-level access permissions in Anvil.

Invalid or Missing API Key (401 Unauthorized)

What it means: A 401 Unauthorized response indicates the request did not have proper authentication. The Anvil API requires an API key (in the X-Api-Key header) for every request.

Solution:

  1. Obtain API key: Request an API key from Anvil if you don't already have one

  2. Use correct header format: Include the header exactly as documented: X-Api-Key: <YOUR_API_KEY>

  3. Verify environment URL: Ensure you're calling the correct base URL for your key's environment (testnet vs mainnet)

  4. Secure your key: Store your API key securely and don't expose it in client-side code

Throttled, please try again later.

What it means: A Throttled response occurs when you're making requests faster than the allowed burst rate limit.

Cardano or Anvil: Anvil-specific. This is our API rate limiting control.

Solution:

  1. Implement backoff strategy: Add exponential backoff with retries when you detect a Throttled response

  2. Space out requests: Ensure your application doesn't send too many requests in quick succession

  3. Batch operations: Where possible, combine multiple operations into single API calls

  4. Monitor usage: Track your API consumption to anticipate potential throttling issues

Daily quota exceeded, please contact Anvil support.

What it means: This error occurs when you've exceeded your daily API quota allocation.

Cardano or Anvil: Anvil-specific. This is an API usage quota control.

Solution:

  1. Review API usage: Analyze your daily API usage patterns to identify optimization opportunities

  2. Optimize requests: Reduce unnecessary API calls in your application code

  3. Request quota increase: If your use case legitimately requires a higher quota, contact Anvil support at [email protected]

  4. Implement caching: Where appropriate, cache API responses to reduce the number of calls

Blueprint Validator Ownership Conflict (Validators in Another Blueprint)

What it means: This error message: "Failed to upsert blueprint: Some validators are associated with another blueprint" (500 Internal Server Error) occurs when you attempt to register or update a smart contract blueprint (CIP-57 blueprint) that contains validators (scripts) which are already tied to a different blueprint.

Cardano or Anvil: Anvil-specific – this is about Anvil's blueprint management component, not a Cardano on-chain error.

Solution:

  1. Contact support: Reach out to Anvil support with details about your account, the blueprint ID/name, and the specific script hashes

  2. Verify ownership: Be prepared to verify your identity and project ownership as requested

  3. Blueprint resolution: The Anvil team may clear or merge blueprint records so you can upload your blueprint again

PreviousFAQNextSelect Cardano Environment

Last updated

Was this helpful?