Errors

Errors can be used to handle validation and other conditions that may occur during the execution of a smart contract. If an error is thrown during the execution of a smart contract call, the execution is stopped and any changes made during the transaction are reverted.

To throw an error, use the assert or panic functions:

assert is used to validate conditions. If the check fails, an error is thrown along with a specified value, often a message. It's similar to the require statement in Solidity.
panic immediately halts the execution with the given error value. It should be used for complex condition checks and for internal errors. It's similar to the revert statement in Solidity. You can use panic_with_felt252 to directly pass a felt252 as the error value.

The assert_eq!, assert_ne!, assert_lt!, assert_le!, assert_gt! and assert_ge! macros can be used as an assert shorthand to compare two values, but only in tests. In contracts, you should only use the assert function.

Here's a simple example that demonstrates the use of these functions:

#[starknet::contract]
pub mod ErrorsExample {
    #[storage]
    struct Storage {}
 
    #[abi(embed_v0)]
    impl ErrorsExample of super::IErrorsExample<ContractState> {
        fn test_assert(self: @ContractState, i: u256) {
            // Assert used to validate a condition
            // and abort execution if the condition is not met
            assert(i > 0, 'i must be greater than 0');
        }
 
        fn test_panic(self: @ContractState, i: u256) {
            if (i == 0) {
                // Panic used to abort execution directly
                core::panic_with_felt252('i must not be 0');
            }
        }
    }
}

Custom errors

You can make error handling easier by defining your error codes in a specific module.

pub mod Errors {
    pub const NOT_POSITIVE: felt252 = 'must be greater than 0';
    pub const NOT_NULL: felt252 = 'must not be null';
}
 
#[starknet::contract]
pub mod CustomErrorsExample {
    use super::Errors;
 
    #[storage]
    struct Storage {}
 
    #[abi(embed_v0)]
    impl CustomErrorsExample of super::ICustomErrorsExample<ContractState> {
        fn test_assert(self: @ContractState, i: u256) {
            assert(i > 0, Errors::NOT_POSITIVE);
        }
 
        fn test_panic(self: @ContractState, i: u256) {
            if (i == 0) {
                core::panic_with_felt252(Errors::NOT_NULL);
            }
        }
    }
}

Vault example

Here's another example that demonstrates the use of errors in a more complex contract:

pub mod VaultErrors {
    pub const INSUFFICIENT_BALANCE: felt252 = 'insufficient_balance';
    // you can define more errors here
}
 
#[starknet::contract]
pub mod VaultErrorsExample {
    use starknet::storage::{StoragePointerReadAccess, StoragePointerWriteAccess};
    use super::VaultErrors;
 
    #[storage]
    struct Storage {
        balance: u256,
    }
 
    #[abi(embed_v0)]
    impl VaultErrorsExample of super::IVaultErrorsExample<ContractState> {
        fn deposit(ref self: ContractState, amount: u256) {
            let mut balance = self.balance.read();
            balance = balance + amount;
            self.balance.write(balance);
        }
 
        fn withdraw(ref self: ContractState, amount: u256) {
            let mut balance = self.balance.read();
 
            assert(balance >= amount, VaultErrors::INSUFFICIENT_BALANCE);
 
            // Or using panic:
            if (balance < amount) {
                core::panic_with_felt252(VaultErrors::INSUFFICIENT_BALANCE);
            }
 
            let balance = balance - amount;
 
            self.balance.write(balance);
        }
    }
}