How to debug failed XRPL transactions?
Last updated:
Debugging failed XRPL transactions requires systematic investigation of transaction details, error codes, account states, and network conditions. Effective debugging practices help developers identify root causes quickly and implement appropriate fixes, whether in application code, transaction parameters, or user guidance.
Start by retrieving the complete transaction record using the tx method with the transaction hash. This returns comprehensive transaction details including the transaction type, parameters, result code, metadata, and the ledger index where it was validated (or attempted). The result code is the first clue - tes codes mean success, while tec, tem, ter, and tef codes indicate different failure types.
Examine the transaction result code carefully. tesSUCCESS indicates the transaction worked. tecUNFUNDED_PAYMENT means insufficient balance. temBAD_SIGNATURE suggests signature problems. terRETRY indicates retry might succeed. tefPAST_SEQ means the sequence number was already used. Each code points to specific investigation areas.
For tec codes (claimed fee failures), check the account state at the time of transaction execution. Query the account using the account_info method with the ledger_index matching the failed transaction. Examine the account's XRP balance, reserve requirements, trust lines, and other relevant state. Often tec failures result from insufficient balance or reserves.
Verify transaction parameters against requirements. Check that amounts are properly formatted (drops for XRP, with value, currency, and issuer for other currencies). Confirm destination tags are included when required. Validate that currency codes are either three-letter ASCII or 40-character hex. Ensure flags are set correctly using bitwise values or the Flags field.
For tem codes (malformed), investigate signature generation. Verify that the private key used for signing matches the account's master or regular key. Check that transaction signing includes all required fields. Confirm that the Sequence number is correct. Ensure the Fee is properly specified in drops. Validate that the transaction JSON structure is correct before signing.
Sequence number issues cause many failures. If the sequence is too low (already used), you get tefPAST_SEQ. If too high (skipping numbers), you get terPRE_SEQ. Query the account's current sequence number using account_info and ensure your transactions use consecutive sequence numbers starting from the current value.
LastLedgerSequence expiration (tefMAX_LEDGER) indicates the transaction didn't validate in time. Check network congestion, transaction fees, and LastLedgerSequence values. During busy periods, increase fees for priority or extend LastLedgerSequence to allow more time. Very short LastLedgerSequence windows cause frequent expiration.
For cross-currency payment failures, investigate pathfinding and liquidity. Use the ripple_path_find method to discover current payment paths between currencies. Check if adequate liquidity exists for the payment amount. Verify that the specified path is still valid - order books change constantly, and paths identified earlier may no longer work.
Partial payment issues require checking the tfPartialPayment flag and delivered_amount. If a partial payment delivered less than expected, liquidity was insufficient. If partial payment behavior wasn't intended, ensure the flag isn't accidentally set. Validate that applications credit based on delivered_amount, not the Amount field.
Trust line failures often relate to reserves. Creating trust lines requires 2 XRP per line in reserve. If tecNO_LINE_INSUF_RES occurs, the account lacks sufficient XRP for the increased reserve. Check the account's available XRP after accounting for existing reserves.
Offer placement failures (tecUNFUNDED_OFFER) mean insufficient balance for the offer. Verify the account holds the currency and amount being offered, accounting for reserves. Remember that placing an offer doesn't immediately transfer funds - they must be available when the offer executes.
Destination account issues cause several error types. tecNO_DST_INSUF_XRP means sending to a new address without meeting the account reserve. tecDST_TAG_NEEDED indicates the destination requires a destination tag but none was provided. Check destination account flags and requirements.
Use block explorers like Bithomp, XRPSCAN, or XRPScan.com to visualize transactions and accounts. These tools present transaction data in user-friendly formats, showing balances, transaction histories, and error details graphically. They're particularly useful for non-developers investigating issues.
Test transactions on the Testnet before deploying to Mainnet. The Testnet mirrors Mainnet functionality but uses worthless test XRP, allowing safe experimentation. Generate test accounts, obtain test XRP from faucets, and thoroughly test transaction types in realistic conditions.
Implement comprehensive logging in applications. Log transaction parameters before submission, transaction hashes after submission, and results after validation. Include timestamps, account addresses, and all relevant details. Good logging makes debugging much easier when issues occur.
Monitor for patterns in failures. If specific transaction types consistently fail, the issue might be in transaction construction. If failures correlate with specific accounts, investigate those accounts' configurations. If failures happen during particular times, network congestion or external service issues might be responsible.
Query transaction fees using the fee method to understand current network conditions. Elevated fees indicate congestion, which can cause low-fee transactions to fail or expire. Adjust application fee logic to respond to current network conditions dynamically.
Understanding rippled server responses helps debugging. Pay attention to error messages in API responses - they often provide additional context beyond error codes. The warnings field in responses indicates potential issues even for successful requests.