Errors & outcomes
SDK error classes, Core failures, transaction outcome semantics and safe note reconciliation patterns.
The SDK distinguishes deterministic rejection from an ambiguous transaction result. Do not retry an unknown spend by releasing its input note without reconciliation.
SDK errors
| Error | Meaning |
|---|---|
LookupTableRequiredError | A private proof transaction lacks a configured validated LUT or v0 signing adapter. |
TransactionFailedError | Solana finalized the transaction with an execution error; the error is available as outcome. |
TransactionUnknownError | Submission/confirmation could not be reconciled; retain reservation and check again. |
MerkleArchiveError | A page, directory, commitment or reconstructed root failed archive validation. |
MerkleReconstructionError | History-based reconstruction failed; inspect its code such as HISTORY_GAP, ROOT_MISMATCH or HISTORY_RPC. |
The SDK also throws descriptive Error instances for conditions such as insufficient private balance, unsupported pool mint, missing prover, invalid LUT state, slippage or malformed note data.
Core errors developers commonly encounter
| Core error | Typical cause |
|---|---|
InvalidZkProof | Wrong proof/public input encoding or failed pairing check. |
InvalidRoot / InvalidTreeGeneration | Root is no longer accepted or tree identity does not match. |
NullifierSpent / InvalidNullifier | Replay attempt or noncanonical spent PDA. |
InvalidPrivateSwapAmount | Public amounts do not match Core CPMM math/constraints. |
SlippageExceeded | Output is below minAmountOut. |
TreeNeedsRollover / TreeRolloverNotReady | Append capacity is insufficient or rollover is premature. |
InvalidMerkleArchive / InvalidMerklePage | Directory, PDA, page contents, offset or digest is invalid. |
InvalidTokenProgram | Program is not classic SPL Token. |
Safe outcome handling
Use buildAndSendOutcome() when you need a tagged union. A finalized success is success; a finalized failure is failure; unknown remains unresolved. The shielded wallet journals pending state and exposes reconcilePending() after restarts. Never infer finality from a returned signature or relay submitted status alone.
Complete code and retry rules are in Confirmation lifecycle and Recovery & witnesses.