Program
Errors
Every error the Geode program can return to a client's transaction, with its code, its message, the instructions that raise it and why.
Program errors are Anchor custom errors: code 6000 plus the variant's index in GeodeError. A refused transaction reports them as custom program error: 0x... with the code in hex, and its logs name the variant. The relayer surfaces the program's refusal in programError (see API errors): UnknownRoot, InvalidProof and DuplicateNullifier become UNKNOWN_ROOT, PROOF_INVALID and NULLIFIER_SPENT, never retryable, and InsufficientPoolFunds becomes INSUFFICIENT_BALANCE.
Program errors
| Code | Hex | Name | Message | Raised by | Why |
|---|---|---|---|---|---|
| 6001 | 0x1771 | UnauthorizedRelayer | The signing relayer is not authorized. | pay, unshield | The signer is not in config.relayers |
| 6002 | 0x1772 | InvalidFee | The fee does not equal the configured rounded-down share. | pay | fee is not floor(price * fee_bps / 10000) |
| 6004 | 0x1774 | InvalidRecipient | The destination does not match the proof or configured payee. | unshield, and every lamport move | unshield: recipient differs from recipient_account, or is the pool vault. Any direct lamport move whose source and destination are the same account |
| 6005 | 0x1775 | InvalidAmount | The amount must be positive. | shield, pay, unshield | amount (or price in pay) is 0 |
| 6006 | 0x1776 | ArithmeticOverflow | A lamport calculation overflowed. | pay, unshield | relayer_refund overflows u64; price + fee + relayer_refund (pay) or amount + relayer_refund (unshield) overflows u64; or a destination balance would overflow u64 |
| 6007 | 0x1777 | MemoTooLarge | Each encrypted note memo must be at most 80 bytes. | shield, pay, unshield | A memo is longer than 80 bytes |
| 6008 | 0x1778 | InvalidReceipt | The storage bucket or term is invalid. | pay | receipt.bucket is not a power of two from 65,536 through 67,108,864, or receipt.term is above 2 |
| 6009 | 0x1779 | NonCanonicalField | A scalar is not a canonical BN254 field element. | shield, pay, unshield | A public input (root, a nullifier or a commitment) is not below the BN254 scalar modulus, or a Poseidon input is not |
| 6010 | 0x177a | PoseidonFailed | The Poseidon syscall failed. | shield, pay, unshield | The Poseidon syscall returned an error while hashing the tree, the receipt or a binding |
| 6011 | 0x177b | DuplicateNullifier | Both input nullifiers must differ. | shield, pay, unshield | nullifiers[0] equals nullifiers[1]. Both nullifier PDAs are created during account validation, before this check, so equal nullifiers name one PDA and its second creation is refused first (see below) |
| 6012 | 0x177c | UnknownRoot | The proof root is not in the recent-root ring. | shield, pay, unshield | root is not among the ring's recent roots: the pool never produced it, or 128 later spends have replaced it. Refresh the tree and prove again |
| 6013 | 0x177d | TreeFull | The commitment tree is full. | shield, pay, unshield | next_leaf_index is above 226 - 2, so two more leaves do not fit |
| 6014 | 0x177e | InvalidProof | The Groth16 proof does not verify for this instruction. | shield, pay, unshield | The proof does not verify over the seven public inputs. Raised whenever any bound value differs from what was proven: depositor, recipient, relayer, amount, price, fee, relayer_refund, receipt fields or memos |
| 6015 | 0x177f | InsufficientPoolFunds | The vault cannot cover the transfer and its rent minimum. | pay, unshield | A debit (the price, fee or relayer_refund in pay, the amount or relayer_refund in unshield) would take the pool vault below its rent-exempt minimum |
Errors outside the program
Some refusals come before the handler runs and carry no Geode code.
| Refusal | Raised by | Why |
|---|---|---|
System Program custom program error: 0x0, "already in use" | shield, pay, unshield | A nullifier PDA already exists, so the note was already spent |
| System Program insufficient lamports | shield, pay, unshield | The signer cannot fund the deposit or the rent of the accounts it creates |
Anchor ConstraintSeeds (2006) | Every instruction | A PDA account is not at its seeds |
| Anchor signer and writable checks (3010, 2000) | Every instruction | The signer did not sign, or a writable account was passed read-only |