Troubleshooting
Diagnose note scanning, witness generation, proof verification, deposits, and unshield failures.
Find what you're seeing below:
- A note does not appear
- Sync fails or is slow
- No spendable note is selected
- The SDK rejects the call before proving
- The Merkle root is unknown
- The deposit reverts
- The proof is invalid
- A nullifier or commitment is rejected
- The unshield or external call reverts
Every contract error is listed in the contract reference.
A revert is safe to retry
A reverted transaction consumes no notes and inserts nothing. Fix the cause, rebuild the call, and send it again.
A note does not appear
Check the chain ID and pool address used to create and scan the encrypted note. Both are authenticated with the ciphertext, so a note prepared for another domain is intentionally ignored.
Then check:
- Did sync include the event? Look for the
NoteCommittedorReturnShieldedlog that created the note. - Is the commitment the pool's? The scanner needs the commitment the pool emitted, not one you computed.
- Is it the right view key? It has to belong to the meta-address the note was sent to.
- Is the payload intact? Ciphertext, ephemerals, view tag, and nonce must match what was emitted.
Synchronization fails or is slow
A single getLogs call from block zero can exceed an RPC provider's block-range
or response-size limit. Pass fromBlock as the pool's deployment block and set
blockRange to a value your provider accepts. Persist lastBlock and pass the
previous result back as previous on the next sync. See
sync incrementally.
Sync incomplete
After rebuilding the tree, getLogs asks the pool whether the root is known at
lastBlock. Sync incomplete means it is not: the RPC dropped a log, a chunk
was skipped, or previous came from a different pool or chain. Sync again from
the deploy block, with a smaller blockRange if the provider truncates
responses. A reorg below lastBlock has the same effect; sync a few blocks
behind the head.
No spendable note is selected
A view key can decrypt notes and calculate their nullifiers, but it cannot
derive the one-time spend secret. Make sure the spending key is available at
spend time and that the derived secret opens the note's ownerPubKey.
Selection also requires enough value in at most eight notes of the token. Supported circuit widths are 1, 2, 4, and 8; unused input slots are represented by zero-value padding inputs.
The SDK rejects the call before proving
OpertusClient validates a spend before it calls the prover:
| Error message | Cause |
|---|---|
Value is not conserved | Output values plus the public amount do not equal the selected inputs |
Output "…" must be a real stealth note | An output is missing; all three outputs are required |
Output "…" is for a different token | An output note was prepared for another token |
Selected note has no ownerSecret | The spend secret was not derived with KeyManager.computeStealthSecret |
… notes do not fit a …-input circuit | More notes were selected than circuitSize allows |
The Merkle root is unknown
Rebuild the pool's one tree from events in leaf-index order. getLogs throws
when a leaf index is missing, because a LeanIMT built over a gap has a different
root. Use the root recorded after the transaction's final insertion. An empty
pool has root 0, which is never known.
Old roots do not expire, so an honestly emitted historical root should remain known. Common causes are skipped logs, inserting a ciphertext instead of its commitment, building a tree from an incremental sync without the earlier leaves, or computing intermediate roots that the pool never committed.
The deposit reverts
Map the reported error before rebuilding the transaction:
| Error | Meaning | What to verify |
|---|---|---|
InvalidPublicAmount | Transfer or note value is zero or out of bounds, or native value does not match | Gross amount, note bound, and exact msg.value for native deposits |
NoteValueMismatch | Measured arrival minus the deposit fee differs from the prepared note | Token transfer behavior, live fee, and predicted net note value |
CommitmentMismatch | Submitted commitment does not match its declared opening | Token, value, owner public key, randomness, and blind |
InvalidCommitment | A field is invalid, the owner key is zero, or the commitment already exists | Field ranges, nonzero owner key, and fresh opening data |
For ERC-20 deposits, also check allowance and token transfer behavior. Predict the note from the actual net accounting, not merely the requested transfer.
The proof is invalid
An InvalidProof usually means a public signal differs from the proof that was
generated. Recheck each group of proof inputs:
| Group | Fields |
|---|---|
| Circuit | Width and nullifier count |
| Tree and token | Root, token, public amount, and clone salt |
| Domain | Chain ID and pool address |
| Outputs | All three encrypted output notes |
| Unshield only | Target, calldata, current protocol fee, and the complete return list |
Changing any bound field after proving invalidates the proof. A transfer uses
public amount zero and salt zero. An unshield uses the gross public amount, and
a nonzero salt must have the correct spend-scalar and diversifier preimage. If
you pass unshieldFeeBps explicitly, make sure it is the pool's live rate.
Also verify that the prover was created with artifacts for the selected width. Missing artifacts fail before a valid proof can be produced.
A nullifier or commitment is rejected
NullifierAlreadySpent means an input note was already consumed. Refresh pool
events and remove it from local spendable state.
Within one call, the outputs must be distinct, and return commitments must
differ from all three outputs and from earlier returns; otherwise the pool
reverts with InvalidCommitment. A commitment that is already in the tree from
an earlier call is accepted, but it shares the first copy's nullifier, so only
one copy can be spent. The SDK flags later copies duplicate and refuses to
spend them. Sender.prepareSend uses fresh opening data for every note, so this
only happens when opening data is reused.
The unshield or external call reverts
For a plain public payout, calldata and the return list must both be empty and
salt must be zero, or the pool reverts with InvalidPublicAmount. A zero
target reverts with InvalidRecipient.
For a composed call, match the error to its check:
| Check | Error |
|---|---|
| No more than four return tokens are listed | TooManyReturns |
| No token appears twice | DuplicateReturn |
Every measured return meets its minValue | SlippageExceeded |
| The target is not the pool or executor | InvalidRecipient |
| The target is not another protocol address | ForbiddenTarget |
| The live fee rate matches the one used while proving | InvalidProof |
| The external call itself succeeds | CallFailed |
| The clone received the full net, which a fee-on-transfer token does not | CloneUnderpaid |
Returned assets that aren't named in the list don't cause a revert; they stay on the clone instead of becoming notes.
External call data is public; see the privacy model.
Still stuck?
Work from the outside in, and stop at the first thing that doesn't match: the chain ID and pool address, then the synced events, then your note state (decryption, nullifiers, tree ID), then the proof inputs, and finally the contract's token accounting and fees.