Error Classes
Runtime errors are organized into the following classes:Transaction Validation (0xFFFFFF00)
Transaction Validation (0xFFFFFF00)
Errors that occur while validating the transaction before any state is loaded (e.g., signature verification).
Transaction Pre-Execute (0xFFFFFE00)
Transaction Pre-Execute (0xFFFFFE00)
Errors that occur while advancing the nonce or collecting fees, before actual program execution.
Transaction Execute (0xFFFFFD00)
Transaction Execute (0xFFFFFD00)
Errors that occur during the course of program execution.
Transaction Post-Execute (0xFFFFFC00)
Transaction Post-Execute (0xFFFFFC00)
Fatal errors that should never happen during normal operation. These are not consensus enforceable and indicate system-level failures.
Block Validation (0xFFFFE400)
Block Validation (0xFFFFE400)
Errors that occur during block validation processes.
Success Code
Indicates successful transaction execution with no errors.
Transaction Validation Errors
These errors occur during the initial validation phase before any state is loaded:The transaction format is invalid or malformed.
The transaction version is not supported or invalid.
The transaction contains invalid or unsupported flags.
The transaction signature is invalid or verification failed.
The transaction contains duplicate account references.
The account list in the transaction is not properly sorted. See Transaction Account Lists for sorting requirements.
The read-write account list is not properly sorted. See Transaction Account Lists for sorting requirements.
The read-only account list is not properly sorted. See Transaction Account Lists for sorting requirements.
The transaction references more accounts than the maximum allowed limit.
Transaction Pre-Execute Errors
These errors occur during nonce advancement and fee collection:The transaction nonce is lower than the account’s current nonce. See Transaction Format for nonce requirements.
The transaction nonce is higher than the account’s expected next nonce. See Transaction Format for nonce requirements.
The fee payer account does not have sufficient balance to cover transaction fees.
The specified fee payer account does not exist in the ledger.
The transaction is not yet valid according to its validity time constraints.
The transaction has expired and is no longer valid for execution.
The provided state proof for the fee payer account is invalid.
The type of state proof provided for the fee payer is not valid or supported.
The slot reference in the fee payer state proof is invalid or outdated.
Transaction Execute Errors
These errors occur during program execution:The virtual machine encountered a fatal error during program execution.
The specified program account is invalid, not executable, or does not exist.
The program explicitly reverted execution, rolling back all changes. See exit syscall for revert behavior.
This error may indicate the program set a user error code. Consult the program’s documentation or implementation for details. A negative user error code may indicate the error code is for a failed syscall - see syscalls documentation for details.
The transaction has exhausted its compute unit (CU) allowance. See Compute Units for resource management.
The transaction has exhausted its storage unit (SU) allowance. See Memory Units for resource management.
Error Handling
When debugging transaction failures, first identify the error class to understand at which stage the transaction failed, then examine the specific error code for detailed troubleshooting information.