The #[account] Constraints

Field attributes on accounts struct members compose validation rules. Anchor evaluates them in a defined order before your instruction handler runs.

Recipe

#[account(
    mut,
    has_one = authority,
    constraint = vault.amount > 0 @ MyError::InvalidAmount,
)]
pub vault: Account<'info, Vault>,

Constraint expressions may reference only sibling account fields and instruction arguments declared with #[instruction(...)]. A bare amount here would not compile; if it really is an instruction argument, add #[instruction(amount: u64)] to the struct.

When to reach for this: You express ownership, relationships, or custom invariants declaratively.

Working Example

#[derive(Accounts)]
#[instruction(new_fee_bps: u16)]
pub struct SetFee<'info> {
    #[account(
        mut,
        seeds = [b"config"],
        bump = config.bump,
        has_one = admin,
        constraint = new_fee_bps <= 10_000 @ ConfigError::FeeTooHigh,
    )]
    pub config: Account<'info, Config>,
    pub admin: Signer<'info>,
}

What this demonstrates:

• #[instruction(...)] brings the handler's arguments into constraint scope; it must list them in order, starting from the first
• mut marks writable accounts
• has_one checks pubkey equality to nested field
• constraint runs arbitrary boolean expressions
• Error after @ maps to custom error enum variant

Deep Dive

Common Attributes

Combine attributes; all must pass.

Gotchas

• constraint without @ error - Generic constraint violation message. Fix: Add @ MyError::Variant for clarity.
• has_one typo - Silent failure to compile or wrong field. Fix: Field name must exist on account struct.
• address = wrong key - Bricks mainnet if hardcoded test key. Fix: Use pubkey! constants per cluster feature flags.
• mut missing on has_one target - Read-only when you need write. Fix: Add mut on accounts you persist.
• Overlapping constraint and handler check - Duplicated logic drifts. Fix: Pick declarative or handler, not both for same rule.

Alternatives

FAQs

Related

• Custom Constraints - advanced expressions
• Account Validation Order - evaluation order
• init & init_if_needed - lifecycle constraints

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.