Exit codes

An exit code is a 32-bit signed integer that indicates whether the compute or action phase of the transaction was successful. If not, it 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 the 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.

Table of exit codes

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

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.

fun drop(): void asm "DROP"

fun onInternalMessage() {
    try {
        // Removes 100 elements from the stack, causing an underflow
        repeat(100){
            drop();
        }
    } catch(exitCode) {
        // exitCode is 2
        assert (exitCode == 2) throw 1111;
    }
}

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!
fun stackOverflow(): void asm
"""
    x{} SLICE        // s
    BLESS            // c
    0 SETNUMARGS     // c'
    2 PUSHINT        // c' 2
    SWAP             // 2 c'
    1 -1 SETCONTARGS // ← this blows up
"""

fun onInternalMessage() {
    try {
        stackOverflow();
    } catch(exitCode) {
        // exitCode is 3
        assert (exitCode == 3) throw 1111;
    }
}

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.

fun touch<T>(y: T): void asm "NOP" // so that the compiler doesn't remove instructions
fun pow2(y: int): int asm "POW2"

fun onInternalMessage() {
    var x = -pow2(255) - pow2(255);
    var zero = x - x;

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

    try {
        touch(x / zero); // division by zero!
    } catch (exitCode) {
        // exitCode is 4
        assert (exitCode == 4) throw 1111;
    }

    try {
        touch(x * x * x); // integer overflow!
    } catch (exitCode) {
        // exitCode is 4
        assert (exitCode == 4) throw 1111;
    }

    // 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:

fun touch<T>(y: T): void asm "NOP" // so that the compiler doesn't remove instructions
fun pow2(y: int): int asm "POW2"

fun onInternalMessage() {
    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 (pow2(55)) {
            touch("smash. I. must.");
        }
    } catch(exitCode) {
        // exitCode is 5
        assert (exitCode == 5) throw 1111;
    }

    try {
        // Builder.storeUint() function can only use up to 256 bits, thus 512 is too much:
        touch(beginCell().storeUint(-1, 512).toCell());
    } catch (exitCode) {
        // exitCode is 5
        assert (exitCode == 5) throw 1111;
    }

    try {
        touch(beginCell().storeUint(100, 2).toCell()); // maximum value is 2^{2} - 1 = 3 < 100
    }
    catch(exitCode) {
        // exitCode is 5
        assert (exitCode == 5) throw 1111;
    }

    try {
        val deployMsg = createMessage({
            bounce: false,
            dest: {
                workchain: 0,
                stateInit: {
                    code: beginCell().endCell(),
                    data: beginCell().endCell(),
                },
                toShard: {
                    fixedPrefixLength: pow2(52), // but fixedPrefixLength is uint5
                    closeTo: contract.getAddress()
                },
            },
            value: 1,
            body: beginCell().endCell(),
        });

        deployMsg.send(SEND_MODE_PAY_FEES_SEPARATELY);
    } catch (exitCode) {
        // exitCode is 5
        assert (exitCode == 5) throw 1111;
    }
}

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
fun invalidOpcode(): void asm "42 SETCP"

fun onInternalMessage() {
    try {
        invalidOpcode();
    } catch (exitCode) {
        // exitCode is 6
        assert (exitCode == 6) throw 1111;
    }
}

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.

fun touch<T>(y: T): void asm "NOP" // so that the compiler doesn't remove instructions
// The actual returned value type doesn't match the declared one
fun typeCheckError(): cell asm "42 PUSHINT";

fun onInternalMessage() {
    try {
        // it isn't cell
        touch(typeCheckError().beginParse());
    } catch (exitCode) {
        // exitCode is 7
        assert (exitCode == 7) throw 1111;
    }
}

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

fun touch<T>(y: T): void asm "NOP" // so that the compiler doesn't remove instructions

fun onInternalMessage() {
    // Too many bits
    try {
        val data = beginCell()
            .storeInt(0, 250)
            .storeInt(0, 250)
            .storeInt(0, 250)
            .storeInt(0, 250)
            .storeInt(0, 24) // 1024 bits!
            .toCell();
        touch(data);
    } catch (exitCode) {
        // exitCode is 8
        assert (exitCode == 8) throw 1111;
    }

    // Too many refs
    try {
        val data = beginCell()
            .storeRef(beginCell().endCell())
            .storeRef(beginCell().endCell())
            .storeRef(beginCell().endCell())
            .storeRef(beginCell().endCell())
            .storeRef(beginCell().endCell()) // 5 refs!
            .toCell();
        touch(data);
    } catch (exitCode) {
        // exitCode is 8
        assert (exitCode == 8) throw 1111;
    }
}

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().

fun touch<T>(y: T): void asm "NOP" // so that the compiler doesn't remove instructions

fun onInternalMessage() {
    // Too few bits
    try {
        touch(beginCell().endCell().beginParse().loadInt(1)); // 0 bits!
    } catch (exitCode) {
        // exitCode is 9
        assert (exitCode == 9) throw 1111;
    }

    // Too few refs
    try {
        touch(beginCell().endCell().beginParse().loadRef()); // 0 refs!
    } catch (exitCode) {
        // exitCode is 9
        assert (exitCode == 9) throw 1111;
    }
}

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:

import "@stdlib/tvm-dicts";

fun touch<T>(y: T): void asm "NOP" // so that the compiler doesn't remove instructions
fun cast<T, U>(y: T): U asm "NOP"
fun cell?.addIntToIDict(mutate self, key: int, number: int): void {
    return self.iDictSetBuilder(32, key, beginCell().storeInt(number, 32));
}

fun onInternalMessage() {
    var dict = createEmptyDict();
    dict.addIntToIDict(0, 0);
    dict.addIntToIDict(1, 1);

    // The Int to Int dictionary is being misinterpreted as a map<int32, cell>
    val m: map<int32, cell> = cast(dict);

    try {
        // And the error happens only when we touch it
        touch(m.get(0).isFound);
    } catch (exitCode) {
        // exitCode is 10
        assert (exitCode == 10) throw 1111;
    }
}

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.

fun sendMessage(msg: cell, mode: int): void asm "SENDMSG"

fun onInternalMessage() {
    try {
        // fails in the Compute phase when the message is ill-formed
        sendMessage(beginCell().endCell(), 0);
    } catch (exitCode) {
        // exitCode is 11
        assert (exitCode == 11) throw 1111;
    }
}

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.

import "@stdlib/gas-payments";

fun onInternalMessage() {
    setGasLimit(100);
}

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

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.

import "@stdlib/gas-payments";

fun onInternalMessage() {
    // For example, let's attempt to queue the 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) {
        reserveToncoinsOnBalance(1000000, RESERVE_MODE_AT_MOST);
    }
}

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.

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

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.

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.

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

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.

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