---
title: Virtual Machine Errors and Fault Codes
description: Virtual machine error codes, fault types, and syscall errors for the Thru VM
source_url:
  html: https://thru.org/docs/spec/vm/errors/
  md: https://thru.org/docs/spec/vm/errors.md
---

# Virtual Machine Errors and Fault Codes

This document contains VM-specific error codes, fault types, and syscall errors that can occur during program execution in the Thru virtual machine.

## VM Error Codes

These errors occur at the virtual machine level during program execution:

**`TN_VM_SUCCESS` · *0x00000000 (0)***

Virtual machine execution completed successfully.

**`TN_VM_ERR_SIGTEXT` · *0xFFFFFFFFFFFFFFFF (-1)***

Invalid or corrupted program text/code segment. This indicates the executable format is malformed or the program code cannot be loaded properly.

**`TN_VM_ERR_SIGILL` · *0xFFFFFFFFFFFFFFFE (-2)***

Illegal instruction encountered during execution. The program attempted to execute an invalid or unsupported instruction. See [Instruction Set](https://thru.org/docs/spec/vm/instruction-set.md) for supported operations.

**`TN_VM_ERR_SIGSEGV` · *0xFFFFFFFFFFFFFFFD (-3)***

Segmentation fault - invalid memory access. The program attempted to access memory outside its allocated segments or violated memory protection rules. See [Memory Layout](https://thru.org/docs/spec/vm/memory-layout.md) for segment boundaries.

**`TN_VM_ERR_SIGFAULT` · *0xFFFFFFFFFFFFFFFC (-4)***

General memory fault. A memory operation failed due to invalid addressing or protection violations.

**`TN_VM_ERR_SIGCU` · *0xFFFFFFFFFFFFFFFB (-5)***

Compute units (CU) exhausted during execution. The program exceeded its allocated computational resources. See [Compute Units](https://thru.org/docs/spec/runtime/resources.md#compute-units) for resource limits.

**`TN_VM_ERR_SIGSU` · *0xFFFFFFFFFFFFFFFA (-6)***

Storage units (SU) exhausted during execution. The program exceeded its allocated memory/storage resources. See [Memory Units](https://thru.org/docs/spec/runtime/resources.md#memory-units) for resource limits.

## VM Fault Types

**`TN_VM_FAULT_REVERT` · *0x01***

Program execution was explicitly reverted. The program called the [exit syscall](https://thru.org/docs/spec/vm/syscalls/exit.md) with a revert instruction.

**`TN_VM_FAULT_SIGCU` · *0x02***

Compute unit exhaustion fault. Execution halted due to CU limit being reached.

**`TN_VM_FAULT_SIGSU` · *0x03***

Storage unit exhaustion fault. Execution halted due to SU limit being reached.

## Syscall Errors

These errors can occur during syscall execution and are returned by system calls to indicate specific failure conditions:

### Success Codes

**`TN_VM_SYSCALL_SUCCESS` · *0x00000000 (0)***

Syscall completed successfully.

**`TN_VM_SYSCALL_SUCCESS_EXIT` · *0x00000001 (1)***

Syscall completed successfully and program should exit normally.

### Account and Segment Errors

**`TN_VM_ERR_SYSCALL_BAD_SEGMENT_TABLE_SIZE` · *0xFFFFFFFFFFFFFFF9 (-7)***

The segment table size is invalid or corrupted. This may occur when memory layout is incorrectly configured.

**`TN_VM_ERR_SYSCALL_INVALID_ACCOUNT_INDEX` · *0xFFFFFFFFFFFFFFF8 (-8)***

The provided account index is out of bounds or invalid. Account indices must be within the transaction’s account list range.

**`TN_VM_ERR_SYSCALL_ACCOUNT_DOES_NOT_EXIST` · *0xFFFFFFFFFFFFFFF7 (-9)***

The referenced account does not exist in the ledger state. See [account\_create syscall](https://thru.org/docs/spec/vm/syscalls/account_create.md) to create new accounts.

**`TN_VM_ERR_SYSCALL_ACCOUNT_NOT_WRITABLE` · *0xFFFFFFFFFFFFFFF6 (-10)***

Attempted to modify an account that is not marked as writable in the transaction. The account must be included in the read-write account list. See [set\_account\_data\_writable syscall](https://thru.org/docs/spec/vm/syscalls/set_account_data_writable.md).

**`TN_VM_ERR_SYSCALL_ACCOUNT_ALREADY_EXISTS` · *0xFFFFFFFFFFFFFFF1 (-15)***

Attempted to create an account that already exists. Use [account\_create syscall](https://thru.org/docs/spec/vm/syscalls/account_create.md) only for new accounts.

**`TN_VM_ERR_SYSCALL_BAD_ACCOUNT_ADDRESS` · *0xFFFFFFFFFFFFFFF0 (-16)***

The provided account address is malformed or invalid format.

**`TN_VM_ERR_SYSCALL_ACCOUNT_IS_NOT_PROGRAM` · *0xFFFFFFFFFFFFFFEF (-17)***

Attempted a program-specific operation on an account that is not executable/program account.

**`TN_VM_ERR_SYSCALL_ACCOUNT_HAS_DATA` · *0xFFFFFFFFFFFFFFEE (-18)***

Attempted to perform an operation that requires an empty account, but the account contains data. See [account\_delete syscall](https://thru.org/docs/spec/vm/syscalls/account_delete.md) to clear account data.

**`TN_VM_ERR_SYSCALL_INVALID_ACCOUNT` · *0xFFFFFFFFFFFFFFE5 (-27)***

The account reference or structure is invalid or corrupted.

**`TN_VM_ERR_SYSCALL_INVALID_ACCOUNT_DATA_SIZE` · *0xFFFFFFFFFFFFFFDD (-35)***

The specified account data size is invalid or exceeds limits. See [account\_resize syscall](https://thru.org/docs/spec/vm/syscalls/account_resize.md) for resizing constraints.

**`TN_VM_ERR_SYSCALL_PROGRAM_IN_CALL_STACK` · *0xFFFFFFFFFFFFFFCF (-49)***

The attempted operation to mutate the specified account failed because the account is a program currently in the invocation call stack.

### Balance and Transfer Errors

**`TN_VM_ERR_SYSCALL_BALANCE_OVERFLOW` · *0xFFFFFFFFFFFFFFF5 (-11)***

A balance operation would result in integer overflow. This prevents balance corruption.

**`TN_VM_ERR_SYSCALL_INSUFFICIENT_BALANCE` · *0xFFFFFFFFFFFFFFDA (-38)***

Insufficient account balance for the requested transfer operation. See [account\_transfer syscall](https://thru.org/docs/spec/vm/syscalls/account_transfer.md).

### Memory and Segment Errors

**`TN_VM_ERR_SYSCALL_ACCOUNT_TOO_BIG` · *0xFFFFFFFFFFFFFFF4 (-12)***

The account size exceeds maximum allowed limits for account data.

**`TN_VM_ERR_SYSCALL_SEGMENT_ALREADY_MAPPED` · *0xFFFFFFFFFFFFFFED (-19)***

Attempted to map a memory segment that is already mapped or in use.

**`TN_VM_ERR_SYSCALL_INVALID_SEGMENT_ID` · *0xFFFFFFFFFFFFFFEB (-21)***

The provided segment ID is invalid or out of range. See [Memory Layout](https://thru.org/docs/spec/vm/memory-layout.md) for valid segment types.

**`TN_VM_ERR_SYSCALL_INVALID_SEGMENT_SIZE` · *0xFFFFFFFFFFFFFFE4 (-28)***

The requested segment size is invalid (not a multiple of 4096UL), zero, or exceeds limits. See [set\_anonymous\_segment\_sz syscall](https://thru.org/docs/spec/vm/syscalls/set_anonymous_segment_sz.md).

**`TN_VM_ERR_SYSCALL_INSUFFICIENT_PAGES` · *0xFFFFFFFFFFFFFFE6 (-26)***

Insufficient memory pages available for the requested allocation.

**`TN_VM_ERR_SYSCALL_UNFREEABLE_PAGE` · *0xFFFFFFFFFFFFFFE3 (-29)***

Attempted to free a memory page that cannot be freed (e.g., system pages).

**`TN_VM_ERR_SYSCALL_INVALID_ADDRESS` · *0xFFFFFFFFFFFFFFEA (-22)***

The provided memory address is invalid, out of bounds, or improperly aligned.

**`TN_VM_ERR_SYSCALL_INVALID_OFFSET` · *0xFFFFFFFFFFFFFFD9 (-39)***

The provided offset is invalid or out of bounds for the target operation.

### Object and Reference Errors

**`TN_VM_ERR_SYSCALL_INVALID_OBJ_REF_KIND` · *0xFFFFFFFFFFFFFFF3 (-13)***

The object reference type is invalid or not supported for the requested operation.

**`TN_VM_ERR_SYSCALL_OBJ_NOT_WRITABLE` · *0xFFFFFFFFFFFFFFF2 (-14)***

Attempted to modify an object that is not writable or is read-only.

### System and Execution Errors

**`TN_VM_ERR_SYSCALL_BAD_PARAMS` · *0xFFFFFFFFFFFFFFEC (-20)***

Invalid parameters provided to the syscall. Check parameter types, ranges, and requirements.

**`TN_VM_ERR_SYSCALL_CALL_DEPTH_TOO_DEEP` · *0xFFFFFFFFFFFFFFE8 (-24)***

Maximum call depth exceeded. Prevents infinite recursion in [invoke syscall](https://thru.org/docs/spec/vm/syscalls/invoke.md) chains.

**`TN_VM_ERR_SYSCALL_REVERT` · *0xFFFFFFFFFFFFFFE7 (-25)***

Explicit revert requested. The program called [exit syscall](https://thru.org/docs/spec/vm/syscalls/exit.md) with revert flag.

**`TN_VM_SYSCALL_ERR_COMPUTE_UNITS_EXCEEDED` · *0xFFFFFFFFFFFFFFD8 (-40)***

Compute units exhausted during syscall execution. See [Compute Units](https://thru.org/docs/spec/runtime/resources.md#compute-units).

**`TN_VM_ERR_SYSCALL_INVALID_FLAGS` · *0xFFFFFFFFFFFFFFD7 (-41)***

Invalid flags provided to the syscall. See individual syscall documentation for valid flag values.

**`TN_VM_ERR_SYSCALL_INVALID_SIGNATURE` · *0xFFFFFFFFFFFFFFD4 (-44)***

The provided signature is invalid or verification failed. This occurs when creating an EOA account with an invalid Ed25519 signature. See [account\_create\_eoa syscall](https://thru.org/docs/spec/vm/syscalls/account_create_eoa.md) for signature requirements.

### State and Proof Errors

**`TN_VM_ERR_SYSCALL_INVALID_STATE_PROOF` · *0xFFFFFFFFFFFFFFE9 (-23)***

The provided state proof is invalid, corrupted, or does not match the current state.

**`TN_VM_ERR_SYSCALL_INVALID_PROOF_LEN` · *0xFFFFFFFFFFFFFFE0 (-32)***

The proof length is invalid or does not match expected size requirements.

**`TN_VM_ERR_SYSCALL_INVALID_PROOF_SLOT` · *0xFFFFFFFFFFFFFFDF (-33)***

The slot reference in the state proof is invalid or outdated.

### Logging and Event Errors

**`TN_VM_ERR_SYSCALL_LOG_DATA_TOO_LARGE` · *0xFFFFFFFFFFFFFFE2 (-30)***

The log data size exceeds maximum allowed length. See [log syscall](https://thru.org/docs/spec/vm/syscalls/log.md) for size limits.

**`TN_VM_ERR_SYSCALL_EVENT_TOO_LARGE` · *0xFFFFFFFFFFFFFFE1 (-31)***

The event data size exceeds maximum allowed length. See [emit\_event syscall](https://thru.org/docs/spec/vm/syscalls/emit_event.md) for size limits.

**`TN_VM_ERR_SYSCALL_EVENT_IS_ZERO_SIZE` · *0xFFFFFFFFFFFFFFD2 (-46)***

The event data size is zero. Events must contain at least one byte. See [emit\_event syscall](https://thru.org/docs/spec/vm/syscalls/emit_event.md) for event requirements.

### Compression and Special Account Errors

**`TN_VM_ERR_SYSCALL_ACCOUNT_IN_COMPRESSION_TIMEOUT` · *0xFFFFFFFFFFFFFFDE (-34)***

The account is in compression timeout and cannot be accessed. Wait for timeout period to expire.

**`TN_VM_ERR_SYSCALL_INVALID_SEED_LENGTH` · *0xFFFFFFFFFFFFFFDC (-36)***

The seed length for account derivation is invalid. Seeds must meet specific length requirements.

**`TN_VM_ERR_SYSCALL_TXN_HAS_COMPRESSED_ACCOUNT` · *0xFFFFFFFFFFFFFFDB (-37)***

The transaction contains compressed accounts that cannot be processed in this context.

**`TN_VM_ERR_SYSCALL_EPHEMERAL_ACCOUNT_CANNOT_CREATE_PERSISTENT` · *0xFFFFFFFFFFFFFFD6 (-42)***

An ephemeral account attempted to create a persistent account, which is not allowed. Ephemeral accounts can only create other ephemeral accounts. See [account\_create\_ephemeral syscall](https://thru.org/docs/spec/vm/syscalls/account_create_ephemeral.md).

**`TN_VM_ERR_SYSCALL_ACCOUNT_COMPRESSION_NOT_ALLOWED` · *0xFFFFFFFFFFFFFFD5 (-43)***

Compression of this account is not currently allowed. See [account\_compress syscall](https://thru.org/docs/spec/vm/syscalls/account_compress.md).

**`TN_VM_ERR_SYSCALL_ACCOUNT_UNCOMPRESSABLE` · *0xFFFFFFFFFFFFFFD3 (-45)***

The account cannot be compressed. The account has flags or properties that prevent compression. See [account\_compress syscall](https://thru.org/docs/spec/vm/syscalls/account_compress.md).

### State Counter Errors

**`TN_VM_ERR_SYSCALL_STATE_BYTES_ADDED_OVERFLOW` · *0xFFFFFFFFFFFFFFD1 (-47)***

The state bytes counter would overflow when adding activated state bytes. This occurs during account creation or decompression operations when the global activated state counter (GASC) would exceed maximum bounds. See [account\_create](https://thru.org/docs/spec/vm/syscalls/account_create.md), [account\_create\_ephemeral](https://thru.org/docs/spec/vm/syscalls/account_create_ephemeral.md), [account\_create\_eoa](https://thru.org/docs/spec/vm/syscalls/account_create_eoa.md), and [account\_decompress](https://thru.org/docs/spec/vm/syscalls/account_decompress.md) syscalls.

**`TN_VM_ERR_SYSCALL_STATE_BYTES_REMOVED_OVERFLOW` · *0xFFFFFFFFFFFFFFD0 (-48)***

The state bytes counter would overflow when adding deactivated state bytes. This occurs during account deletion or compression operations when the global deactivated state counter (GDSC) would exceed maximum bounds. See [account\_delete](https://thru.org/docs/spec/vm/syscalls/account_delete.md) and [account\_compress](https://thru.org/docs/spec/vm/syscalls/account_compress.md) syscalls.

## Error Handling

> **Tip:**
>
> VM errors typically occur during program execution and may indicate issues with program logic, resource management, or invalid operations. Check the program implementation and ensure proper error handling for syscall operations.

> **Note:**
>
> Virtual machine-level errors (fault codes and syscall errors) typically occur during program execution and may indicate issues with program logic, resource management, or invalid operations. Check the program implementation and ensure proper error handling for syscall operations.

> **Note:**
>
> For runtime-level errors that occur outside of VM execution, see [Runtime Errors](https://thru.org/docs/spec/runtime/errors.md).