---
title: Runtime Errors
description: Complete reference of Thru runtime transaction errors organized by error class
source_url:
  html: https://thru.org/docs/spec/runtime/errors/
  md: https://thru.org/docs/spec/runtime/errors.md
---

# 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.

> **Tip:**
>
> For the authoritative, up-to-date error list, also check `src/thru/runtime/tn_runtime_errors.h`.

## 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

**`TN_RUNTIME_TXN_EXECUTE_SUCCESS` · *0x00000000 (0)***

Indicates successful transaction execution with no errors.

## 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](https://thru.org/docs/spec/core/transactions.md#account-addresses) 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](https://thru.org/docs/spec/core/transactions.md#account-addresses) 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](https://thru.org/docs/spec/core/transactions.md#account-addresses) 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

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](https://thru.org/docs/spec/core/transactions.md#field-descriptions) 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](https://thru.org/docs/spec/core/transactions.md#field-descriptions) 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

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](https://thru.org/docs/spec/vm/syscalls/exit.md) for revert behavior.

> **Note:**
>
> 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](https://thru.org/docs/spec/vm/syscalls/overview.md) for details.

**`TN_RUNTIME_TXN_ERR_CU_EXHAUSTED` · *0xFFFFFD04 (-764)***

The transaction has exhausted its compute unit (CU) allowance. See [Compute Units](https://thru.org/docs/spec/runtime/resources.md#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](https://thru.org/docs/spec/runtime/resources.md#memory-units) for resource management.

For VM-specific errors including syscall errors, fault codes, and virtual machine execution errors, see [VM Errors](https://thru.org/docs/spec/vm/errors.md).

## Error Handling

> **Tip:**
>
> 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.