Cairo provides robust error handling mechanisms for smart contracts. When an error occurs during contract execution, the transaction is immediately reverted and all state changes are undone.

​
Basic Error Functions

Cairo offers two main functions for error handling:

​
1. assert

  • Used for condition validation (similar to Solidity’s require)
  • Stops execution if the condition is false
  • Supports two formats: 
    assert(condition, 'error message');           // Basic assertion
assert!(condition, "formatted error: {}", x); // Formatted string error

​
2. panic

  • Used for immediate execution halt (similar to Solidity’s revert)
  • Best for complex conditions or internal errors
  • Supports multiple formats: 
    panic_with_felt252('error message');           // Basic panic
panic!("formatted error: value={}", value);    // Formatted string error
While Cairo provides assertion macros like assert_eq! and assert_ne!, these are only for testing. In contract code, always use the standard assert function.

​
Simple Example

Here’s a basic example demonstrating both error handling approaches: 
#[starknet::interface]
trait ISimpleErrors<TContractState> {
    fn check_positive(self: @TContractState, value: u128) -> bool;
    fn set_value(ref self: TContractState, value: u128);
}

#[starknet::contract]
mod SimpleErrors {
    use starknet::storage::{StoragePointerReadAccess, StoragePointerWriteAccess};

    #[storage]
    struct Storage {
        value: u128,
    }

    #[abi(embed_v0)]
    impl SimpleErrors of super::ISimpleErrors<ContractState> {
        fn check_positive(self: @ContractState, value: u128) -> bool {
            // Using assert for validation
            assert(value > 0, 'Value must be positive');
            true
        }

        fn set_value(ref self: ContractState, value: u128) {
            // Using panic for immediate halt
            if value == 0 {
                panic_with_felt252('Value cannot be zero');
            }
            self.value.write(value);
        }
    }
}

​
Custom Error Codes

For better organization and consistency, you can define error messages in a dedicated module: 
mod Errors {
    const INSUFFICIENT_BALANCE: felt252 = 'Insufficient balance';
    const INVALID_AMOUNT: felt252 = 'Invalid amount';
    const ACCESS_DENIED: felt252 = 'Access denied';
}

#[starknet::interface]
trait ICustomErrors<TContractState> {
    fn withdraw(ref self: TContractState, amount: u128);
}

#[starknet::contract]
mod CustomErrors {
    use starknet::storage::{StoragePointerReadAccess, StoragePointerWriteAccess};
    use super::Errors;

    #[storage]
    struct Storage {
        balance: u128,
    }

    #[abi(embed_v0)]
    impl CustomErrors of super::ICustomErrors<ContractState> {
        fn withdraw(ref self: ContractState, amount: u128) {
            // Using custom error constants
            assert(amount > 0, Errors::INVALID_AMOUNT);
            assert(self.balance.read() >= amount, Errors::INSUFFICIENT_BALANCE);
            
            let new_balance = self.balance.read() - amount;
            self.balance.write(new_balance);
        }
    }
}

​
Real-World Example: Vault Contract

Here’s a practical example showing error handling in a vault contract that manages deposits and withdrawals: 
mod Errors {
    const INSUFFICIENT_BALANCE: felt252 = 'Insufficient balance';
    const INVALID_AMOUNT: felt252 = 'Invalid amount';
    const ACCESS_DENIED: felt252 = 'Access denied';
}

#[starknet::interface]
trait IVaultErrors<TContractState> {
    fn deposit(ref self: TContractState, amount: u128);
    fn withdraw(ref self: TContractState, amount: u128);
    fn get_balance(self: @TContractState) -> u128;
}

#[starknet::contract]
mod VaultErrors {
    use starknet::storage::{StoragePointerReadAccess, StoragePointerWriteAccess};
    use super::Errors;

    #[storage]
    struct Storage {
        balance: u128,
        owner: ContractAddress,
    }

    #[constructor]
    fn constructor(ref self: ContractState, owner: ContractAddress) {
        self.owner.write(owner);
    }

    #[abi(embed_v0)]
    impl VaultErrors of super::IVaultErrors<ContractState> {
        fn deposit(ref self: ContractState, amount: u128) {
            assert(amount > 0, Errors::INVALID_AMOUNT);
            let current_balance = self.balance.read();
            self.balance.write(current_balance + amount);
        }

        fn withdraw(ref self: ContractState, amount: u128) {
            assert(amount > 0, Errors::INVALID_AMOUNT);
            let current_balance = self.balance.read();
            
            if current_balance < amount {
                panic_with_felt252(Errors::INSUFFICIENT_BALANCE);
            }
            
            self.balance.write(current_balance - amount);
        }

        fn get_balance(self: @ContractState) -> u128 {
            self.balance.read()
        }
    }
}
In this example:
  1. Custom errors are defined in a separate module
  2. The withdraw function demonstrates both assert and panic approaches
  3. Balance checks protect against underflow conditions