Runtime Errors
The Thru runtime defines specific error codes that can occur during transaction processing. These errors are categorized into different classes based on when they occur in the transaction lifecycle.
Error Classes
Section titled “Error Classes”Runtime errors are organized into the following classes:
Transaction Validation (0xFFFFFF00)
Errors that occur while validating the transaction before any state is loaded (e.g., signature verification).
Transaction Pre-Execute (0xFFFFFE00)
Errors that occur while advancing the nonce or collecting fees, before actual program execution.
Transaction Execute (0xFFFFFD00)
Errors that occur during the course of program execution.
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)
Errors that occur during block validation processes.
Success Code
Section titled “Success Code”TN_RUNTIME_TXN_EXECUTE_SUCCESS · 0x00000000 (0)
Indicates successful transaction execution with no errors.
Transaction Validation Errors
Section titled “Transaction Validation Errors”These errors occur during the initial validation phase before any state is loaded:
TN_RUNTIME_TXN_ERR_INVALID_FORMAT · 0xFFFFFF01 (-255)
The transaction format is invalid or malformed.
TN_RUNTIME_TXN_ERR_INVALID_VERSION · 0xFFFFFF02 (-254)
The transaction version is not supported or invalid.
TN_RUNTIME_TXN_ERR_INVALID_FLAGS · 0xFFFFFF03 (-253)
The transaction contains invalid or unsupported flags.
TN_RUNTIME_TXN_ERR_INVALID_SIGNATURE · 0xFFFFFF04 (-252)
The transaction signature is invalid or verification failed.
TN_RUNTIME_TXN_ERR_DUPLICATE_ACCOUNT · 0xFFFFFF05 (-251)
The transaction contains duplicate account references.
TN_RUNTIME_TXN_ERR_UNSORTED_ACCOUNTS · 0xFFFFFF06 (-250)
The account list in the transaction is not properly sorted. See Transaction Account Lists for sorting requirements.
TN_RUNTIME_TXN_ERR_UNSORTED_READWRITE_ACCOUNTS · 0xFFFFFF07 (-249)
The read-write account list is not properly sorted. See Transaction Account Lists for sorting requirements.
TN_RUNTIME_TXN_ERR_UNSORTED_READONLY_ACCOUNTS · 0xFFFFFF08 (-248)
The read-only account list is not properly sorted. See Transaction Account Lists for sorting requirements.
TN_RUNTIME_TXN_ERR_ACCOUNT_COUNT_LIMIT_EXCEEDED · 0xFFFFFF09 (-247)
The transaction references more accounts than the maximum allowed limit.
TN_RUNTIME_TXN_ERR_CHAIN_ID_ZERO · 0xFFFFFF0A (-246)
The transaction chain ID is zero, which is not allowed.
Transaction Pre-Execute Errors
Section titled “Transaction Pre-Execute Errors”These errors occur during nonce advancement and fee collection:
TN_RUNTIME_TXN_ERR_NONCE_TOO_LOW · 0xFFFFFE01 (-511)
The transaction nonce is lower than the account’s current nonce. See Transaction Format for nonce requirements.
TN_RUNTIME_TXN_ERR_NONCE_TOO_HIGH · 0xFFFFFE02 (-510)
The transaction nonce is higher than the account’s expected next nonce. See Transaction Format for nonce requirements.
TN_RUNTIME_TXN_ERR_INSUFFICIENT_FEE_PAYER_BALANCE · 0xFFFFFE03 (-509)
The fee payer account does not have sufficient balance to cover transaction fees.
TN_RUNTIME_TXN_ERR_FEE_PAYER_ACCOUNT_DOES_NOT_EXIST · 0xFFFFFE04 (-508)
The specified fee payer account does not exist in the ledger.
TN_RUNTIME_TXN_ERR_NOT_LIVE_YET · 0xFFFFFE05 (-507)
The transaction is not yet valid according to its validity time constraints.
TN_RUNTIME_TXN_ERR_EXPIRED · 0xFFFFFE06 (-506)
The transaction has expired and is no longer valid for execution.
TN_RUNTIME_TXN_ERR_INVALID_FEE_PAYER_STATE_PROOF · 0xFFFFFE07 (-505)
The provided state proof for the fee payer account is invalid.
TN_RUNTIME_TXN_ERR_INVALID_FEE_PAYER_STATE_PROOF_TYPE · 0xFFFFFE08 (-504)
The type of state proof provided for the fee payer is not valid or supported.
TN_RUNTIME_TXN_ERR_INVALID_FEE_PAYER_STATE_PROOF_SLOT · 0xFFFFFE09 (-503)
The slot reference in the fee payer state proof is invalid or outdated.
TN_RUNTIME_TXN_ERR_INVALID_FEE_PAYER_ACCOUNT_OWNER · 0xFFFFFE0A (-502)
The fee payer account owner is invalid.
TN_RUNTIME_TXN_ERR_INVALID_FEE_PAYER_STATE_PROOF_ACCOUNT_OWNER · 0xFFFFFE0B (-501)
The fee payer state proof account owner does not match expected ownership.
TN_RUNTIME_TXN_ERR_INVALID_FEE_PAYER_STATE_PROOF_ACCOUNT_META_DATA_SZ · 0xFFFFFE0C (-500)
The fee payer state proof account metadata size is invalid.
TN_RUNTIME_TXN_ERR_CHAIN_ID_MISMATCH · 0xFFFFFE0D (-499)
The transaction chain ID does not match the runtime chain ID.
TN_RUNTIME_TXN_ERR_FEE_PAYER_IN_COMPRESSION_TIMEOUT · 0xFFFFFE0E (-498)
The fee payer account is still within the compression cooldown window and cannot be uncompressed via a fee-payer state proof. Wait until the cooldown has elapsed before submitting the transaction.
Transaction Execute Errors
Section titled “Transaction Execute Errors”These errors occur during program execution:
TN_RUNTIME_TXN_ERR_VM_FAILED · 0xFFFFFD01 (-767)
The virtual machine encountered a fatal error during program execution.
TN_RUNTIME_TXN_ERR_INVALID_PROGRAM_ACCOUNT · 0xFFFFFD02 (-766)
The specified program account is invalid, not executable, or does not exist.
TN_RUNTIME_TXN_ERR_VM_REVERT · 0xFFFFFD03 (-765)
The program explicitly reverted execution, rolling back all changes. See exit syscall for revert behavior.
TN_RUNTIME_TXN_ERR_CU_EXHAUSTED · 0xFFFFFD04 (-764)
The transaction has exhausted its compute unit (CU) allowance. See Compute Units for resource management.
TN_RUNTIME_TXN_ERR_SU_EXHAUSTED · 0xFFFFFD05 (-763)
The transaction has exhausted its storage unit (SU) allowance. See Memory Units for resource management.
For VM-specific errors including syscall errors, fault codes, and virtual machine execution errors, see VM Errors.