Unrecoverable Errors with panic

In Cairo, unexpected issues may arise during program execution, resulting in runtime errors. While the panic function from the core library doesn't provide a resolution for these errors, it does acknowledge their occurrence and terminates the program. There are two primary ways that a panic can be triggered in Cairo: inadvertently, through actions causing the code to panic (e.g., accessing an array beyond its bounds), or deliberately, by invoking the panic function.

When a panic occurs, it leads to an abrupt termination of the program. The panic function take an array as argument, which can be used to provide an error message and performs an unwind process where all variables are dropped and dictionaries squashed to ensure the soundness of the program to safely terminate the execution.

Here is how we can panic from inside a program and return the error code 2:

use array::ArrayTrait;
use debug::PrintTrait;

fn main() {
    let mut data = ArrayTrait::new();
    data.append(2);
    panic(data);
    'This line isn't reached'.print();
}

Running the program will produce the following output:

$ cairo-run test.cairo
Run panicked with err values: [2]

As you can notice in the output, the print statement is never reached, as the program terminates after encountering the panic statement.

An alternative and more idiomatic approach to panic in Cairo would be to use the panic_with_felt252 function. This function serves as an abstraction of the array-defining process and is often preferred due to its clearer and more concise expression of intent. By using panic_with_felt252, developers can panic in a one-liner by providing a felt252 error message as argument, making the code more readable and maintainable.

Let's consider an example:

fn main() {
    panic_with_felt252(2);
}

Executing this program will yield the same error message as before. In that case, if there is no need for an array and multiple values to be returned within the error, so panic_with_felt252 is a more succinct alternative.

Using assert

The assert function from the Cairo core library is actually a utility function based on panics. It asserts that a boolean expression is true at runtime, and if it is not, it calls the panic function with an error value. The assert function takes two arguments: the boolean expression to verify, and the error value. The error value is specified as a felt252, so any string passed must be able to fit inside a felt252.

Here is an example of its usage:

fn main() {
    let my_number: u8 = 0;

    assert(my_number != 0, 'number is zero');

    100 / my_number;
}

We are asserting in main that my_number is not zero to ensure that we're not performing a division by 0. In this example, my_number is zero so the assertion will fail, and the program will panic with the string 'number is zero' (as a felt252) and the division will not be reached.