TVM exit codes

An exit code is a 32-bit signed integer, which indicates whether the compute or action phase of the transaction was successful, and if not — holds the code of the exception that occurred.

Each transaction on TON Blockchain consists of multiple phases. An exit code is a 32-bit signed integer that indicates whether the compute or action phase of the transaction was successful, and if not — holds the code of the exception that occurred. Each exit code represents its own exception or resulting state of the transaction.

Exit codes 0 and 1 indicate normal (successful) execution of the compute phase. Exit (or result) code 0 indicates normal (successful) execution of the action phase. Any other exit code indicates that a certain exception has occurred and that the transaction was not successful in one way or another, i.e. the transaction was reverted or the inbound message has bounced back.

TON Blockchain reserves exit code values from 0 to 127. The range from 256 to 65535 is free for developer-defined exit codes.

While an exit (or result) code is a 32-bit signed integer on TON Blockchain, an attempt to throw an exit code outside the bounds of a 16-bit unsigned integer ($0 - 65535$) will cause an error with exit code 5. This is done intentionally to prevent some exit codes from being produced artificially, such as exit code -14.

Table of exit codes

The following table lists exit codes with their origin (where they can occur) and a short description for each.

Exit code	Origin	Brief description
0	Compute and action phases	Standard successful execution exit code.
1	Compute phase	Alternative successful execution exit code. Reserved, but does not occur.
2	Compute phase	Stack underflow.
3	Compute phase	Stack overflow.
4	Compute phase	Integer overflow.
5	Compute phase	Range check error — an integer is out of its expected range.
6	Compute phase	Invalid TVM opcode.
7	Compute phase	Type check error.
8	Compute phase	Cell overflow.
9	Compute phase	Cell underflow.
10	Compute phase	Dictionary error.
11	Compute phase	Described in TVM docs as “Unknown error, may be thrown by user programs.”
12	Compute phase	Fatal error. Thrown by TVM in situations deemed impossible.
13	Compute phase	Out of gas error.
-14	Compute phase	Same as 13. Negative, so that it cannot be faked.
14	Compute phase	VM virtualization error. Reserved, but never thrown.
32	Action phase	Action list is invalid.
33	Action phase	Action list is too long.
34	Action phase	Action is invalid or not supported.
35	Action phase	Invalid source address in outbound message.
36	Action phase	Invalid destination address in outbound message.
37	Action phase	Not enough Toncoin.
38	Action phase	Not enough extra currencies.
39	Action phase	Outbound message does not fit into a cell after rewriting.
40	Action phase	Cannot process a message — not enough funds, the message is too large, or its Merkle depth is too big.
41	Action phase	Library reference is null during library change action.
42	Action phase	Library change action error.
43	Action phase	Exceeded the maximum number of cells in the library or the maximum depth of the Merkle tree.
50	Action phase	Account state size exceeded limits.

Often enough, you might encounter the exit code 65535 (or 0xffff), which usually means the same as the exit code 130 — the received opcode is unknown to the contract, as there were no receivers expecting it. When writing contracts, the exit code 65535 is set by the developers and not by TVM or the Tolk compiler.

Exit codes in Blueprint projects

In Blueprint tests, exit codes from the compute phase are specified in the exitCode field of the object argument for the toHaveTransaction() method of the expect() matcher. The field for the result codes (exit codes from the action phase) in the same toHaveTransaction() method is called actionResultCode.

Additionally, one can examine the result of sending a message to a contract and discover the phases of each transaction and their values, including exit (or result) codes for the compute phase (or action phase).

Note that to do so, you’ll have to perform a couple of type checks first:

it('tests something, you name it', async () => {
  // Send a specific message to our contract and store the results
  const res = await your_contract_name.send({/* … */});

  // Now, we have access to an array of executed transactions,
  // with the second one (index 1) being the one we look for
  const tx = res.transactions[1]!;

  // To do something useful with it, let's ensure that its type is 'generic'
  // and that the compute phase in it wasn't skipped
  if (tx.description.type === "generic"
      && tx.description.computePhase.type === "vm") {
    // Finally, we're able to freely peek into the transaction for general details,
    // such as printing out the exit code of the compute phase if we so desire
    console.log(tx.description.computePhase.exitCode);
  }
});

Compute and action phases

0: Normal termination

This exit (or result) code indicates the successful completion of the compute phase (or action phase) of the transaction.

Compute phase

TVM initialization and all computations occur in the compute phase.

If the compute phase fails (the resulting exit code is neither 0 nor 1), the transaction skips the action phase and proceeds to the bounce phase. In this phase, a bounce message is formed for transactions initiated by the inbound message.

1: Alternative termination

This is an alternative exit code for the successful execution of the compute phase. It is reserved but never occurs.

2: Stack underflow

If an operation consumes more elements than exist on the stack, an error with exit code 2 is thrown: Stack underflow.

asm fun drop() { DROP }

contract Loot {
    receive("I solemnly swear that I'm up to no good") {
        try {
            // Removes 100 elements from the stack, causing an underflow
            repeat (100) { drop() }
        } catch (exitCode) {
            // exitCode is 2
        }
    }
}

Useful links

TVM overview.

3: Stack overflow

If there are too many elements copied into a closure continuation, an error with exit code 3 is thrown: Stack overflow. This occurs rarely unless you’re deep in the Fift and TVM assembly trenches:

// Remember kids, don't try to overflow the stack at home!
asm fun stackOverflow() {
    x{} SLICE        // s
    BLESS            // c
    0 SETNUMARGS     // c'
    2 PUSHINT        // c' 2
    SWAP             // 2 c'
    1 -1 SETCONTARGS // ← this blows up
}

contract ItsSoOver {
    receive("I solemnly swear that I'm up to no good") {
        try {
            stackOverflow();
        } catch (exitCode) {
            // exitCode is 3
        }
    }
}

Useful links

TVM overview.

4: Integer overflow

If the value in a calculation goes beyond the range from $-2^{256}$ to $2^{256} - 1$ inclusive, or there’s an attempt to divide or perform modulo by zero, an error with exit code 4 is thrown: Integer overflow.

let x = -pow(2, 255) - pow(2, 255); // -2^{256}

try {
    -x; // integer overflow by negation
        // since the max positive value is 2^{256} - 1
} catch (exitCode) {
    // exitCode is 4
}

try {
    x / 0; // division by zero!
} catch (exitCode) {
    // exitCode is 4
}

try {
    x * x * x; // integer overflow!
} catch (exitCode) {
    // exitCode is 4
}

// There can also be an integer overflow when performing:
// addition (+),
// subtraction (-),
// division (/) by a negative number or modulo (%) by zero

5: Integer out of expected range

A range check error occurs when some integer is out of its expected range. Any attempt to store an unexpected amount of data or specify an out-of-bounds value throws an error with exit code 5: Integer out of expected range.

Examples of specifying an out-of-bounds value:

try {
    // Repeat only operates on an inclusive range from 1 to 2^{31} - 1
    // Any valid integer value greater than that causes an error with exit code 5
    repeat (pow(2, 55)) {
        dump("smash. logs. I. must.");
    }
} catch (exitCode) {
    // exitCode is 5
}

try {
    // Builder.storeUint() function can only use up to 256 bits, thus 512 is too much:
    let s: Slice = beginCell().storeUint(-1, 512).asSlice();
} catch (exitCode) {
    // exitCode is 5
}

6: Invalid opcode

If you specify an instruction that is not defined in the current TVM version or attempt to set an unsupported code page, an error with exit code 6 is thrown: Invalid opcode.

// There's no such code page, and an attempt to set it fails
asm fun invalidOpcode() { 42 SETCP }

contract OpOp {
    receive("I solemnly swear that I'm up to no good") {
        try {
            invalidOpcode();
        } catch (exitCode) {
            // exitCode is 6
        }
    }
}

7: Type check error

If an argument to a primitive is of an incorrect value type or there is any other mismatch in types during the compute phase, an error with exit code 7 is thrown: Type check error.

// The actual returned value type doesn't match the declared one
asm fun typeCheckError(): map<Int, Int> { 42 PUSHINT }

contract VibeCheck {
    receive("I solemnly swear that I'm up to no good") {
        try {
            // The 0th index doesn't exist
            typeCheckError().get(0)!!;
        } catch (exitCode) {
            // exitCode is 7
        }
    }
}

8: Cell overflow

To construct a cell, a builder primitive is used. If you try to store more than 1023 bits of data or more than 4 references to other cells, an error with exit code 8 is thrown: Cell overflow.

This error can be triggered by manual construction of the cells via relevant methods, such as storeInt(), or when using structs their convenience methods.

// Too many bits
try {
    let data = beginCell()
        .storeInt(0, 250)
        .storeInt(0, 250)
        .storeInt(0, 250)
        .storeInt(0, 250)
        .storeInt(0, 24) // 1024 bits!
        .endCell();
} catch (exitCode) {
    // exitCode is 8
}

// Too many refs
try {
    let data = beginCell()
        .storeRef(emptyCell())
        .storeRef(emptyCell())
        .storeRef(emptyCell())
        .storeRef(emptyCell())
        .storeRef(emptyCell()) // 5 refs!
        .endCell();
} catch (exitCode) {
    // exitCode is 8
}

9: Cell underflow

To parse a cell, a slice primitive is used. If you try to load more data or references than a slice contains, an error with exit code 9 is thrown: Cell underflow.

The most common cause of this error is a mismatch between the expected and actual memory layouts of the cells, so it’s recommended to use Tolk structs for parsing the cells instead of manual parsing via relevant methods, such as loadInt().

// Too few bits
try {
    emptySlice().loadInt(1); // 0 bits!
} catch (exitCode) {
    // exitCode is 9
}

// Too few refs
try {
    emptySlice().loadRef(); // 0 refs!
} catch (exitCode) {
    // exitCode is 9
}

10: Dictionary error

In Tolk, the map<K, V> type is an abstraction over the “hash” map dictionaries of TVM.

If there is incorrect manipulation of dictionaries, such as improper assumptions about their memory layout, an error with exit code 10 is thrown: Dictionary error. Note that Tolk prevents you from getting this error unless you perform TVM assembly work yourself:

/// Pre-computed Int to Int dictionary with two entries — 0: 0 and 1: 1
const cellWithDictIntInt: Cell = cell("te6cckEBBAEAUAABAcABAgPQCAIDAEEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAQQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMLMbT1U=");

/// Tries to preload a dictionary from a Slice as a map<Int, Cell>
asm fun toMapIntCell(x: Slice): map<Int, Cell> { PLDDICT }

contract DictPic {
    receive("I solemnly swear that I'm up to no good") {
        try {
            // The Int to Int dictionary is being misinterpreted as a map<Int, Cell>
            let m: map<Int, Cell> = toMapIntCell(cellWithDictIntInt.beginParse());

            // And the error happens only when we touch it
            m.get(0)!!;
        } catch (exitCode) {
            // exitCode is 10
        }
    }
}

11: “Unknown” error

Described in the TVM docs as “Unknown error, may be thrown by user programs,” although most commonly used for problems with queuing a message send or problems with getters.

In particular, if you try to send an ill-formed message on-chain or to call a non-existent getter function off-chain, an exit code 11 will be thrown.

try {
    // Unlike sendRawMessage which uses SENDRAWMSG, this one uses SENDMSG,
    // and therefore fails in Compute phase when the message is ill-formed
    sendRawMessageReturnForwardFee(emptyCell(), 0);
} catch (exitCode) {
    // exitCode is 11
}

12: Fatal error

Fatal error. Thrown by TVM in situations deemed impossible.

13: Out of gas error

If there isn’t enough gas to complete computations in the compute phase, an error with exit code 13 is thrown: Out of gas error.

However, this code isn’t immediately shown as is — instead, the bitwise NOT operation is applied, changing the value from 13 to -14. Only then is the code displayed.

This is done to prevent the resulting code (-14) from being produced artificially in user contracts, as all functions that can throw an exit code can only specify integers in the range from 0 to 65535 inclusive.

try {
    repeat (pow(2, 31) - 1) {}
} catch (exitCode) {
    // exitCode is -14
}

-14: Out of gas error

See exit code 13.

14: Virtualization error

Virtualization error related to pruned branch cells. Reserved but never thrown.

Action phase

The action phase is processed after the successful execution of the compute phase. It attempts to perform the actions stored in the action list by TVM during the compute phase.

Some actions may fail during processing, in which case those actions may be skipped or the whole transaction may revert depending on the mode of actions. The code indicating the resulting state of the action phase is called a result code. Since it is also a 32-bit signed integer that essentially serves the same purpose as the exit code of the compute phase, it is common to call the result code an exit code as well.

32: Action list is invalid

If the list of actions contains exotic cells, an action entry cell does not have references, or some action entry cell cannot be parsed, an error with exit code 32 is thrown: Action list is invalid.

Aside from this exit code, there is a boolean flag valid, which you can find under description.actionPhase.valid in the transaction results when working with Sandbox and Blueprint. A transaction can set this flag to false even when there is some other exit code thrown from the action phase.

33: Action list is too long

If there are more than 255 actions queued for execution, the action phase will throw an error with an exit code 33: Action list is too long.

// For example, let's attempt to queue reservation of a specific amount of nanoToncoins
// This won't fail in the compute phase, but will result in exit code 33 in the action phase
repeat (256) {
    nativeReserve(ton("0.001"), ReserveAtMost);
}

34: Invalid or unsupported action

There are only four supported actions at the moment: changing the contract code, sending a message, reserving a specific amount of nanoToncoin, and changing the library cell. If there is any issue with the specified action (invalid message, unsupported action, etc.), an error with exit code 34 is thrown: Invalid or unsupported action.

// For example, let's try to send an ill-formed message:
sendRawMessage(emptyCell(), 0); // won't fail in the compute phase,
                                   // but will result in exit code 34 in the Action phase

35: Invalid source address in outbound message

If the source address in the outbound message is not equal to addr_none or to the address of the contract that initiated this message, an error with exit code 35 is thrown: Invalid source address in outbound message.

36: Invalid destination address in outbound message

If the destination address in the outbound message is invalid, e.g., it does not conform to the relevant TL-B schemas, contains an unknown workchain ID, or has an invalid length for the given workchain, an error with exit code 36 is thrown: Invalid destination address in outbound message.

If the optional mode flag +2 is set, this error won’t be thrown, and the given message won’t be sent.

37: Not enough Toncoin

If all funds of the inbound message with base mode 64 set have already been consumed and there are not enough funds to pay for the failed action, or the TL-B layout of the provided value (CurrencyCollection) is invalid, or there are not enough funds to pay forward fees or not enough funds after deducting fees, an error with exit code 37 is thrown: Not enough Toncoin.

If the optional mode flag +2 is set, this error won’t be thrown, and the given message won’t be sent.

38: Not enough extra currencies

Besides the native currency, Toncoin, TON Blockchain supports up to $2^{32}$ extra currencies. They differ from creating new Jettons because extra currencies are natively supported — one can potentially just specify an additional HashmapE of extra currency amounts in addition to the Toncoin amount in the internal message to another contract. Unlike Jettons, extra currencies can only be stored and transferred and do not have any other functionality.

When there is not enough extra currency to send the specified amount is already reserved, an exit code 38 is thrown: Not enough extra currencies.

39: Outbound message does not fit into cell

When processing the message, TON Blockchain tries to pack it according to the relevant TL-B schemas, and if it cannot, an error with exit code 39 is thrown: Outbound message doesn't fit into a cell.

If attempts at sending the message fail multiple times and the optional mode flag +2 is set, this error won’t be thrown, and the given message won’t be sent.

40: Cannot process message

If there are not enough funds to process all the cells in a message, the message is too large, or its Merkle depth is too big, an error with exit code 40 is thrown: Cannot process a message.

If the optional mode flag +2 is set, this error won’t be thrown, and the given message won’t be sent.

41: Library reference is null

If a library reference is required during a library change action but is null, an error with exit code 41 is thrown: Library reference is null.

42: Library change action error

If there’s an error during an attempt at a library change action, an error with exit code 42 is thrown: Library change action error.

43: Library limits exceeded

If the maximum number of cells in the library is exceeded or the maximum depth of the Merkle tree is exceeded, an error with exit code 43 is thrown: Library limits exceeded.

50: Account state size exceeded limits

If the account state (contract storage, essentially) exceeds any of the limits specified in config param 43 of TON Blockchain by the end of the action phase, an error with exit code 50 is thrown: Account state size exceeded limits.

If the configuration is absent, the default values are:

• max_msg_bits is equal to $2^{21}$ — maximum message size in bits.
• max_msg_cells is equal to $2^{13}$ — maximum number of cells a message can occupy.
• max_library_cells is equal to 1000 — maximum number of cells that can be used as library reference cells.
• max_vm_data_depth is equal to $2^{9}$ — maximum cells depth in messages and account state.
• ext_msg_limits.max_size is equal to 65535 — maximum external message size in bits.
• ext_msg_limits.max_depth is equal to $2^{9}$ — maximum external message depth.
• max_acc_state_cells is equal to $2^{16}$ — maximum number of cells that an account state can occupy.
• max_acc_state_bits is equal to $2^{16} \times 1023$ — maximum account state size in bits.
• max_acc_public_libraries is equal to $2^{8}$ — maximum number of library reference cells that an account state can use on the masterchain.
• defer_out_queue_size_limit is equal to $2^{8}$ — maximum number of outbound messages to be queued (regarding validators and collators).