Anchor Errors & Events

Errors, events, and logs are how an Anchor program communicates outcomes that account state alone does not capture: fail with a stable code, publish a typed success record for indexers, or leave a short human trail for engineers. Anchor 0.32.1 wires those channels into the IDL so clients and indexers share one contract with the on-chain binary.

#[error_code] & require! is the hands-on entry; Custom Error Messages, Events with emit!, emit_cpi! & Self-CPI Events, Logging & CU Cost, and Client-Side Error Decoding zoom into each surface. This page is the map underneath.

Summary

• Anchor splits observability into typed errors (#[error_code], require!, error!), structured events (#[event], emit!, emit_cpi!), and budgeted logs (msg!), all exportable through the IDL for off-chain consumers.
• Insight: Users never see your Rust ? chain. They see simulation failures, explorer log lines, and whatever your dApp maps from Custom(u32). Design those surfaces on purpose or you ship opaque "Transaction failed" UX and CU waste.
• Key Concepts: #[error_code], require! / error!, #[msg], constraint @ Error, #[event] / emit! / emit_cpi!, log CU cost, IDL error tables, simulation-first decoding.
• When to Use: Designing failure modes for vaults, markets, or admin paths; instrumenting success for analytics; wiring @solana/kit 7.0.0 or Anchor clients to decode failures; explaining program observability to frontend and indexer teams.
• Limitations/Trade-offs: Every log and event spends compute units; every error code is a public API you must version; failed instructions roll back state; logs and events are public chain data (no secrets).
• Related Topics: error codes and require, custom messages, emit and emit_cpi, logging CU, client-side decoding.

Foundations

An Anchor instruction handler returns Result<()>. Success commits account mutations; failure aborts the instruction (and transaction) and reverts those mutations. There is no partial commit of "error fields." The failure itself is the signal.

That design pushes observability into execution metadata and the IDL, not into durable last_error accounts (unless you write such state on a success path). Three channels fill the gap:

  Anchor handler (Result<()>)
        |
        +-- require! / error! / ?  --> Err(code) --> fail tx + logs so far
        |
        +-- msg!("...")            --> CU cost  --> logMessages
        |
        +-- emit! / emit_cpi!      --> #[event] --> indexers / IDL consumers
        |
        +-- Ok(())                 --> commit account writes

Errors are the control-flow contract. Prefer typed variants for user-facing rules and keep messages product-safe. Logs are a short, prefixed, feature-gated debug channel. Events are the structured channel for off-chain systems that should not scrape prose.

All three share one property: transaction logs are public. Seeds, private keys, PII, and exploit-ready internals do not belong there.

Anchor's advantage over raw ProgramError::Custom is IDL integration: anchor build exports error names, codes, optional #[msg] strings, and event schemas into target/idl/*.json. Clients pin that artifact to the deployed program.

Mechanics & Interactions

#[error_code], require!, and error!

Define domain failures as an enum. Anchor assigns stable numeric codes (conventionally starting at 6000) and includes them in the IDL:

#[error_code]
pub enum VaultError {
    #[msg("Vault is paused")]
    Paused,
    #[msg("Insufficient balance")]
    InsufficientFunds,
    #[msg("Math overflow")]
    Overflow,
}
 
pub fn withdraw(ctx: Context<Withdraw>, amount: u64) -> Result<()> {
    require!(!ctx.accounts.vault.paused, VaultError::Paused);
    require!(
        ctx.accounts.vault.balance >= amount,
        VaultError::InsufficientFunds
    );
    ctx.accounts.vault.balance = ctx.accounts.vault.balance
        .checked_sub(amount)
        .ok_or(VaultError::Overflow)?;
    Ok(())
}

Use constraints for account-time rules so invalid accounts never reach handler body logic:

#[account(constraint = !pool.disabled @ SwapError::PoolDisabled)]
pub pool: Account<'info, Pool>,

Append-only variants so codes never silently remap. Reordering renumbers codes and breaks every client map. Treat the enum like a versioned public API.

Deep dive: #[error_code] & require!.

Custom messages with #[msg]

#[msg("...")] attaches a default English string to each variant. That string lands in the IDL for explorers, AnchorError, and generated tables. It is not a localization system and not a place for dynamic values. Keep strings short, user-safe, and stable.

Off-chain, map codes to product copy, i18n keys, and retry hints. On-chain English is a tooling fallback, not the only UX surface. Details: Custom Error Messages.

Events with emit!

When dashboards or Geyser plugins need reliable fields, free-text msg! parsing becomes a liability. Mark a Borsh-friendly struct with #[event] and publish it on success paths:

#[event]
pub struct PositionOpened {
    pub owner: Pubkey,
    pub market: Pubkey,
    pub size: u64,
    pub timestamp: i64,
}
 
emit!(PositionOpened {
    owner: ctx.accounts.owner.key(),
    market: ctx.accounts.market.key(),
    size,
    timestamp: Clock::get()?.unix_timestamp,
});

Events appear in the IDL. Fields must be public and serializable. Prefer keys and amounts over large blobs. Account state remains authoritative. Failed instructions do not commit state, so design failure UX around error codes, not durable "error events." Deep dive: Events with emit!.

emit_cpi! and self-CPI delivery

Classic emit! logs event data in a form many tools understand, often via an internal self-CPI pattern. emit_cpi! makes the CPI path explicit so indexers that depend on CPI observation capture events more reliably:

emit_cpi!(LiquidityAdded {
    provider: ctx.accounts.provider.key(),
    amount,
});

Standardize one style per program so parsers stay simple. Budget CU after switching to emit_cpi! on hot paths. Details: emit_cpi! & Self-CPI Events.

Logging and compute units

msg! invokes the log syscall. Cost scales with call count and payload size. On a tight CU budget, a loop of formatted logs can tip a transaction into compute exceeded.

Practical rules:

1. Prefer one short line per decision over multi-line dumps.
2. Gate verbose logging behind Cargo features on mainnet builds.
3. Use stable prefixes (VAULT:deposit_ok) for ops grep.
4. Prefer events for production observability; reserve msg! for dev, Surfpool, LiteSVM, and short incidents.
5. Never log secrets (seeds, private metadata, public billboard data only).

Profile with sol_log_compute_units and set a client compute budget when instructions approach limits. See Logging & CU Cost.

Client-side decoding

Wallets often show a generic failure. Your dApp should do better:

1. Run simulateTransaction (or confirm and fetch meta) with the same accounts and data.
2. Extract the failing program ID and custom code (decimal or hex, e.g. 0x1770 = 6000).
3. Map through IDL errors via @coral-xyz/anchor's AnchorError, Codama-generated tables, or a pinned lookup for @solana/kit 7.0.0.
4. Show a product message, optional i18n string, and a code-specific retry hint.

  Simulate message --> InstructionError + logs
        |
        v
  program_id + code --> IDL / generated table
        |
        v
  UI string + retry hint

Pin the decoder artifact to the deployed program hash. Stale IDLs cause wrong error names in support tickets. Always decode with (program_id, code) in multi-program transactions. Patterns: Client-Side Error Decoding.

Observability map for Anchor teams

Errors decide control flow. Logs explain engineers. Events feed machines. Account state settles disputes.

Advanced Considerations & Applications

Constraint vs handler errors. Put identity and account-shape rules in #[derive(Accounts)] with @ YourError::Variant. Put business rules that need computed amounts or CPI results in require! inside the handler.

CPI boundaries. Callee errors may surface in outer logs. Rethrow, wrap into your own UX code, or leave the callee code honest. Decode with (program_id, code), not code alone.

Security and UX. Granular errors help users; over-granular ones can teach attackers which check failed. Prefer stable categories. Put exploit-hunting detail behind gated non-mainnet logs, not permanent #[msg] strings.

Compute budget. Log or event spam can cause failures only under load. Profile CU after upgrades (this site pins Agave 4.1.1) and treat log removal as a real performance change.

Versioning and tests. Tie program binary, IDL, and error table together. Archive decoder artifacts per deploy. Assert specific codes in Anchor/LiteSVM tests so silent renumbering fails CI.

Common Misconceptions

• "I'll return a free-form string and the wallet will show it." Clients primarily see codes and log lines. Design stable #[error_code] variants and decode them yourself.
• "msg! is free debugging." Each call spends compute units and can fail tight budgets.
• "Events are durable storage." They are structured log payloads; account state is the source of truth, and failed instructions do not commit state.
• "I can log seeds; only my team reads logs." Transaction logs are public chain data.
• "Custom error 6001 always means the same thing on Solana." Codes are per program; always pair with program ID.
• "Reordering enum variants is a pure refactor." It renumbers codes and breaks client maps; append only.
• "emit! and emit_cpi! are interchangeable for every indexer." Capture reliability and CU cost differ; pick one style and verify your pipeline.
• "On-chain #[msg] is enough for internationalization." Map codes to locale strings off-chain.

FAQs

Related

• #[error_code] & require! - Declaring and asserting typed errors
• Custom Error Messages - #[msg] strings and stable UX copy
• Events with emit! - Structured #[event] payloads for indexers
• emit_cpi! & Self-CPI Events - Reliable capture via explicit CPI
• Logging & CU Cost - Budget msg! and production observability
• Client-Side Error Decoding - Map IDL codes in TypeScript clients

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1, and @solana/kit 7.0.0.