Exit codes

Each transaction on TON Blockchain consists of multiple phases. 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 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 wasn’t successful in one way or another, i.e. transaction was reverted or the inbound message has bounced back.

TON Blockchain reserves exit code values from $0$ to $127$, while Tact utilizes exit codes from $128$ to $255$. Note, that exit codes used by Tact indicate contract errors which can occur when using Tact-generated FunC code, and are therefore thrown in the transaction’s compute phase and not during the compilation.

The range from $256$ to $65535$ is free for developer-defined exit codes.

Note

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

Table of exit codes

The following table lists exit codes with an origin (where it can occur) and a short description for each. The table doesn’t list the exit code of the require(), as it generates it depending on the concrete error message String.

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 doesn’t occur.
$2$	Compute phase	Stack underflow.
$3$	Compute phase	Stack overflow.
$4$	Compute phase	Integer overflow.
$5$	Compute phase	Range check error — some 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 maximum number of cells in the library or the maximum depth of the Merkle tree.
$50$	Action phase	Account state size exceeded limits.
$128$	Tact compiler (Compute phase)	Null reference exception.
$129$	Tact compiler (Compute phase)	Invalid serialization prefix.
$130$	Tact compiler (Compute phase)	Invalid incoming message — there’s no receiver for the opcode of the received message.
$131$	Tact compiler (Compute phase)	Constraints error. Reserved, but never thrown.
$132$	Tact compiler (Compute phase)	Access denied — someone other than the owner sent a message to the contract.
$133$	Tact compiler (Compute phase)	Contract stopped. Reserved, but never thrown.
$134$	Tact compiler (Compute phase)	Invalid argument.
$135$	Tact compiler (Compute phase)	Code of a contract was not found.
$136$	Tact compiler (Compute phase)	Invalid address. Removed since Tact 1.6
$137$	Tact compiler (Compute phase)	Masterchain support is not enabled for this contract. Removed since Tact 1.6

Note

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 TVMor the Tact 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 toHaveTransaction() method of expect() matcher. The field for the result codes (exit codes from the action phase) in the same toHaveTransaction() method is called actionResultCode.

Note

Read more about expecting specific exit codes: Transactions with intentional errors.

Additionally, one can take a look at 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 compute phase (or action phase).

Note, that in order to do so, you’ll have to do a couple of type checks before that:

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 an access to array of executed transactions,
  // with the second one (index 1) being the one that we look for
  const tx = res.transactions[1]!;

  // To do something useful with it, let's ensure that it's 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 a successful completion of the compute (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 isn’t $0$ or $1$), the transaction skips the action phase and goes to the bounce phase. In it, the bounce message is formed for the transactions initiated by the inbound message.

1: Alternative termination

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

2: Stack underflow

If some operation consumed more elements than there were on the stack, the 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 is a stack machine in TON Docs.

3: Stack overflow

If there are too many elements copied into a closure continuation, an error with exit code $3$ is thrown: Stack overflow. Occurs rarely, unless you’re deep in 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 is a stack machine in TON Docs.

4: Integer overflow

If the value in calculation goes beyond the range from $-2^{256}$ to $2^{256} - 1$ inclusive, or there’s an attempt to divide or 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 doing:
// addition (+),
// subtraction (-),
// division (/) by a negative number or modulo (%) by zero

5: Integer out of range

Range check error — some integer is out of its expected range. I.e. 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 range.

Examples of specifying an out-of-bounds value:

try {
    // Repeat only operates on inclusive range from 1 to 2^{31} - 1
    // and 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, so 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 try to set an unsupported code page, an error with exit code $6$ is thrown: Invalid opcode.

// There's no such codepage, and 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’s 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

From Cells, Builders and Slices page of the Book:

Cell is a primitive and a data structure, which ordinarly consists of up to $1023$ continuously laid out bits and up to $4$ references (refs) to other cells.

To construct a Cell, a Builder 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 .loadSomething() methods or when using Structs and Messages and their convenience methods.

// Too much 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 much 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

From Cells, Builders and Slices page of the Book:

Cell is a primitive and a data structure, which ordinarly consists of up to $1023$ continuously laid out bits and up to $4$ references (refs) to other cells.

To parse a Cell, a Slice is used. If you try to load more data or references than 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 Structs and Messages for parsing of the cells instead of manual parsing via relevant .loadSomething() methods.

// 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 Tact, the map<K, V> type is an abstraction over the “hash” map dictionaries of FunC and underlying HashmapE type of TL-B and TVM.

If there is an incorrect manipulation of dictionaries, such as improper assumptions about their memory layout, an error with exit code $10$ is thrown: Dictionary error. Note, that Tact prevents you from getting this error unless you do Fift and 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 TVM docs as “Unknown error, may be thrown by user programs”, although most commonly used for problems with queueing a message send or problems with get-methods.

try {
    // Unlike nativeSendMessage which uses SENDRAWMSG, this one uses SENDMSG,
    // and therefore fails in Compute phase when the message is ill-formed
    nativeSendMessageReturnForwardFee(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 end computations in the compute phase, the error with exit code $13$ is thrown: Out of gas error.

But this code isn’t immediately shown as is — instead, the bitwise NOT operation is applied, which changes the value from $13$ to $-14$. And only then the code is shown.

That’s done in order to prevent the resulting code ($-14$) from being produced artificially in user contracts, since 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 prunned 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 into 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’s also a $32$-bit signed integer that essentially serves the same purpose as exit code of compute phase, it’s common to call the result code an exit code too.

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 couldn’t be parsed, an error with exit code $32$ is thrown: Action list is invalid.

Note

Aside from this exit code there’s a boolean flag valid, which you can find under description.actionPhase.valid in the transaction results when working with Sandbox and Blueprint. 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 specific amount of nanoToncoins
// This won't fail in compute phase, but will result in exit code 33 in 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 nanoToncoins and changing the library cell. If there’s 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:
nativeSendMessage(emptyCell(), 0); // won't fail in compute phase,
                                   // but will result in exit code 34 in Action phase

35: Invalid source address in outbound message

If the source address in the outbound message isn’t 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 doesn’t conform to the relevant TL-B schemas, contains unknown workchain ID or it has invalid length for the given workchain, an error with exit code $36$ is thrown: Invalid destination address in outbound message.

Note

If the optional 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 had been already consumed and there’s not enough funds to pay for the failed action, or the TL-B layout of the provided value (CurrencyCollection) is invalid, or there’s 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.

Note

If the optional 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 making new Jettons because extra currencies are natively supported — one can potentially just specify an extra 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.

At the moment, there are no extra currencies on TON Blockchain, but the exit code $38$ in cases when there is not enough extra currency to send the specified amount of it is already reserved: Not enough extra currencies.

Useful links:

Extra currencies in TON Docs.
Extra currency mining in TON Docs.

39: Outbound message doesn’t fit into a 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.

Note

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

40: Cannot process a message

If there would not be 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 the library reference was required during library change action, but it was 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 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, 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} * 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 (regards validators and collators).

Tact compiler

Tact utilizes exit codes from $128$ to $255$. Note, that exit codes used by Tact indicate contract errors which can occur when using Tact-generated FunC code, and are therefore thrown in the transaction’s compute phase and not during the compilation.

128: Null reference exception

If there’s a non-null assertion, such as the !! operator, and the checked value is null, an error with exit code $128$ is thrown: Null reference exception.

let gotcha: String? = null;

try {
    // Asserting that the value isn't null, which isn't the case!
    dump(gotcha!!);
} catch (exitCode) {
    // exitCode is 128
}

129: Invalid serialization prefix

Reserved, but due to a number of prior checks it cannot be thrown unless one hijacks the contract code before deployment and changes the opcodes of the Messages expected to be received in the contract.

130: Invalid incoming message

If the received internal or external message isn’t handled by the contract, an error with exit code $130$ is thrown: Invalid incoming message. It usually happens when the contract doesn’t have a receiver for the particular message and its opcode prefix (32-bit integer header).

Consider the following contract:

import "@stdlib/deploy";

contract Dummy with Deployable {}

If you try to send any message, except for Deploy provided by @stdlib/deploy, the contract won’t have a receiver for it and thus would throw an error with exit code $130$.

131: Constraints error

Constraints error. Reserved, but never thrown.

132: Access denied

If you use the Ownable trait from the @stdlib/ownable library, the helper function requireOwner() provided by it will throw an error with exit code $132$ if the sender of the inbound message won’t match the specified owner: Access denied.

import "@stdlib/ownable";

contract Hal9k with Ownable {
    owner: Address;

    init(owner: Address) {
        self.owner = owner; // set the owner address upon deployment
    }

    receive("I'm sorry Dave, I'm afraid I can't do that.") {
        // Checks that the message sender's address equals to the owner address,
        // and if not — throws an error with exit code 132.
        self.requireOwner();

        // ... you do you ...
    }
}

133: Contract stopped

A message has been sent to a stopped contract. Reserved, but never thrown.

134: Invalid argument

If there is an invalid or unexpected argument value, an error with exit code $134$ is thrown: Invalid argument.

Here are some of the functions in Tact which can throw an error with this exit code:

1. Int.toFloatString(digits): if the digits is not in the interval: $0 <$ digits $< 78$.

2. String.fromBase64() and Slice.fromBase64(): if the given String or Slice contains non-Base64 characters.

try {
    // 0 is code of NUL in ASCII and it is not valid Base64
    let code: Slice = beginCell().storeUint(0, 8).asSlice().fromBase64();
} catch (exitCode) {
    // exitCode is 134
}

135: Code of a contract was not found

If the code of the contract doesn’t match the one saved in TypeScript wrappers, the error with exit code $135$ will be thrown: Code of a contract was not found.

136: Invalid address

Removed since Tact 1.6

A value of type Address is valid in Tact when:

• It occupies $267$ bits: $11$ bits for the chain ID prefix and $256$ bits for the address itself.
• It belongs to either basechain (ID $0$) or masterchain (ID $-1$).

If the Address isn’t valid, the error with exit code $136$ will be thrown: Invalid address.

// Only basechain (ID 0) or masterchain (ID -1) are supported by Tact
let unsupportedChainID = 1;

try {
    // Zero address in unsupported workchain
    dump(newAddress(unsupportedChainID, 0));
} catch (exitCode) {
    // exitCode is 136
}

137: Masterchain support is not enabled for this contract

Removed since Tact 1.6

Prior to removal, any attempts to point to masterchain (ID $-1$) or otherwise interact with it without enabling masterchain support were throwing an exception with exit code $137$: Masterchain support is not enabled for this contract.

let masterchainID = -1;

try {
    // Zero address in masterchain without the config option set
    dump(newAddress(masterchainID, 0));
} catch (exitCode) {
    // exitCode is 137
}