Disperse · Errors · 6@tokenops/sdk/fhe-disperse
Disperse errors you can catch by class.
Singleton-shaped errors. Most disperse failures fall into one of three buckets: registration state, subwallet operator approval, FHE-compute envelope hits.
For the catch-ladder pattern + how SDK-level and generic-fallback errors fit alongside these, read Concepts › Typed errors + recovery.
| Class | When thrown | Recovery |
|---|---|---|
| NotRegisteredError | Any user-flow call that needs a registered wallet pair (wallet-mode useDisperse, useApproveTokenOnWallets, useRecoverFromWallets) for a user who has not yet called useRegister. | Registration deploys the two ERC-1167 subwallets and is once per user. useIsRegistered gates the whole user-flow UI, not just disperse. useRegister |
| AlreadyRegisteredError | useRegister called for a user who already registered. register() is single-use per user, not per token. | useIsRegistered short-circuits the registration UI; useGetWallets returns the existing deployed pair. Whitelist additional tokens with useApproveTokenOnWallets. useIsRegistered |
| DisperseSubwalletNotFoundError | useRegister's transaction receipt contained no UserRegistered event from the singleton: the registration may have reverted silently. Not a recipient problem. | Inspect the registration tx by hash and retry useRegister. usePredictWallets shows the pair that should have been deployed. usePredictWallets |
| DisperseEncryptedReserveNotGrantedError | useAccessEncryptedFeeReserve's receipt had no ACL Allowed event granting the caller the fee-reserve handle. Usually the reserve for that token is uninitialized: no fees have accrued yet. | Check that token fees are enabled and at least one fee-charging disperse has run for the token before reading the reserve. useAccessEncryptedFeeReserve |
| BatchTooLargeError | recipients.length exceeds the on-chain configured batch limit for the selected disperse mode (maxBatchSizeHolding, maxBatchSizeDirect, or maxBatchSizeTokenFee — each a mutable state variable set by DEFAULT_ADMIN_ROLE). A limit of 0n means no cap. The SDK checks this before encryption, so no FHE time is spent on an oversized batch. | Chunk the batch to fit the current limit. Call getBatchLimits() (or useGetBatchLimits) to read the live per-mode caps before dispatching. |
| PausedError | Singleton is paused; write-side calls revert until a PAUSER unpauses. | useIsPaused is the precondition check. Surface the paused state in the UI rather than letting useDisperse fail. useIsPaused |
TokenOpsSdkError and carries the offending values under err.context — render specific messages instead of generic "transaction failed."Read the catch ladder