Sign in

Errors and events

Suggest an edit

A handler has to deal with more than the happy path: someone passed a zero amount, the caller isn't authorized, the lockup hasn't expired, the vault is empty. Every one of these conditions needs to abort the transaction with a message the user can read. Separately, when the happy path succeeds, off-chain consumers want to know what changed: who deposited, who withdrew, how much. The first is the job of errors, the second of events.

Errors are an enum, and the order of its variants is fixed

A program's errors are a Rust enum tagged with #[error_code]. Each variant is one failure case, with a human-readable message. The macro turns the enum into something Anchor can return and the IDL can describe.

rust
use anchor_lang::prelude::*;

#[error_code]
pub enum CounterError {
    #[msg("Increment must be greater than zero")]
    ZeroIncrement,

    #[msg("Caller lacks admin authority")]
    Unauthorized,

    #[msg("Counter would overflow")]
    Overflow,

    #[msg("Counter would exceed configured maximum")]
    WouldExceedMax,

    #[msg("Counter is locked")]
    Locked,
}

The numeric error codes start at 6000, because Anchor reserves 0 through 5999 for framework errors. The messages end up in the IDL and are what client tools display when the error fires. The variant order is positional, so once a program is deployed, appending new variants is safe but reordering or inserting breaks every later error code for clients.

require! aborts the transaction when a condition is false

require! covers most checks. The first argument is a boolean expression that must be true. If it isn't, the transaction aborts with the named error.

rust
require!(by > 0, CounterError::ZeroIncrement);
require!(!counter.locked, CounterError::Locked);
require!(
    counter.value + by <= counter.max,
    CounterError::WouldExceedMax,
);

Anchor's macro layer expands each one into the equivalent of an if !condition { return Err(...) }. Three of these stacked at the top of a handler is a normal pattern.

The other forms exist for the sake of the log. A failed require! logs only the error name. When the check is equality between two values, require_eq!, or its negation require_neq!, also logs both values as two lines, for example Left: 100 and Right: 250, which saves a debugging round trip when a test fails. It works for integers and any other type that implements Display. A byte array or a type that only implements Debug does not compile with it. require_keys_eq! and require_keys_neq! do the same for two pubkeys and log them in base58:

rust
// authority check
require_keys_eq!(
    ctx.accounts.admin.key(),
    counter.admin,
    CounterError::Unauthorized,
);

For the rare path that needs to log diagnostic info before erroring, fall back to the explicit form: an if that calls msg! and ends with return Err(ERR.into()). The .into() converts your enum variant into the anchor_lang::error::Error type that handlers return. If a require! works, prefer it.

Account checks go in the struct, argument checks in the handler

The authority check above compares the key of the admin account with the key stored in counter, and the constraints lesson already has a place for that: has_one = admin on the counter field does the same comparison before the handler runs:

rust
#[derive(Accounts)]
pub struct Increment<'info> {
    #[account(mut, has_one = admin @ CounterError::Unauthorized)]
    pub counter: Account<'info, Counter>,
    pub admin: Signer<'info>,
}

The @ CounterError::Unauthorized part makes a failed check return your Unauthorized error instead of Anchor's generic ConstraintHasOne. Who an account is and whether it is the right one belongs in the Accounts struct, as has_one, seeds, or constraint = expr @ MyError::SomeReason. What stays in the handler are the rules that depend on the instruction's arguments: the amount is greater than zero, the maximum is not exceeded. A rule about stored state alone, such as the counter not being locked, can be written either way, as require! in the handler or as constraint = expr in the struct.

Events report what a successful transaction did

Errors stop a transaction. Events report what a successful one did. The mechanism is a structured log entry: you define a Rust struct with #[event], then emit it from your handler.

rust
#[event]
pub struct Incremented {
    pub counter: Pubkey,
    pub by: u64,
    pub new_value: u64,
}

// inside the handler:
emit!(Incremented {
    counter: counter.key(),
    by,
    new_value: counter.value,
});

The #[event] macro registers the struct's schema in the IDL, so off-chain code knows how to decode it. The emit! macro inside the handler serializes one instance of the struct and writes it to the transaction's logs.

Indexers like Helius or Triton subscribe to a program's logs, decode every event they care about, and write rows into a database. Frontend code reads from that database to show "the latest deposits" or "recent trades." Discord bots read the same stream and post announcements as events arrive. Account state cannot serve this purpose, because it shows the current values and not how the account got there. The off-chain state lesson covers indexers in detail.

State vs events: where each piece of data belongs

The most common mistake new developers make in this area is treating events as a substitute for on-chain state. They emit an event for some piece of data, then try to read it back from another instruction. It doesn't work, because events are not on-chain readable.

State vs events: two different output channelsTwo side-by-side panels compare state (on accounts) and events (emit!) across written by, lives, cost, readable by, and good for. State lives in the account's data field and is readable by on-chain and off-chain code, while events live in the transaction's logs and can only be read by off-chain consumers, never by on-chain code. State vs events: two different output channels state (on accounts) written by: vault.total += amount; lives: in the account's data field cost: rent + compute paid once at allocation readable by: on-chain code (other programs, later instructions in this tx) off-chain code (RPC, indexers) good for: - the source of truth - anything that gates logic - balances, ownership, status the chain's enforcement layer events (emit!) written by: emit!(Deposited { ... }); lives: in the transaction's logs cost: compute only no rent, no allocation readable by: only off-chain consumers on-chain code can never read events back good for: - analytics, indexers - frontend notifications - structured logs the chain's notification layer If another instruction needs to read it, put it in state. If only humans and dashboards need it, emit it.

If another instruction needs to read it, put it in state. If only humans and dashboards need it, emit it.

State is anything that gates program logic. Balances, ownership flags, lockup expiry timestamps, current proposal status. All of these must live on accounts because some future instruction will need to check them. State costs rent and persists across transactions.

Events are anything that off-chain consumers need to know about but no on-chain logic will read. A deposit happened, a trade executed, a vote was cast. Each of these is interesting to analytics and frontends, but if your program needs to know whether a user already deposited, that check lives on an account rather than in a log.

A handler checks first, then writes state, then emits

Most handlers have the shape of this increment: a few require! calls validating inputs, the state change, and an emit! call announcing what happened. The Increment struct already ties the signer to counter.admin with has_one, so the handler checks only the argument and the counter's state.

rust
#[program]
pub mod counter {
    use super::*;

    pub fn increment(ctx: Context<Increment>, by: u64) -> Result<()> {
        let counter = &mut ctx.accounts.counter;

        // preconditions
        require!(by > 0, CounterError::ZeroIncrement);
        require!(!counter.locked, CounterError::Locked);

        // overflow-safe arithmetic
        let new_value = counter.value
            .checked_add(by)
            .ok_or(CounterError::Overflow)?;

        require!(new_value <= counter.max, CounterError::WouldExceedMax);

        // happy path: update state, emit event
        counter.value = new_value;

        emit!(Incremented {
            counter: counter.key(),
            by,
            new_value: counter.value,
        });

        Ok(())
    }
}

The checks happen up front, before any state changes. If any of them fails, the transaction aborts before counter.value is touched. The checked_add returns Option<u64>, and ok_or converts a None into your custom error, which is the idiomatic way to handle arithmetic that might overflow. The event is emitted at the end, after the state update, so the values in the event reflect what's now on chain.