> For AI agents: the documentation index is at https://sdk.nimbusprivacy.xyz/llms.txt, and every page is available as Markdown at its URL with .md appended. # Troubleshooting (/production/troubleshooting) Find the symptom, then read its section below. | Symptom | Likely cause | Fix | | ------------------------------------------------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `unsupported-browser` saying the page is not cross-origin isolated | The page lacks the two headers | [Send both headers](#not-cross-origin-isolated) | | `dependency-nonconforming` naming a file and two hashes | Files from another SDK version | [Copy the files again](#a-file-digest-mismatch) | | Progress stops at `prepared` | The first proof is downloading circuit files | [Wait, and keep the tab open](#stuck-at-prepared) | | `listWallets` returns nothing | The wallet registered late, or cannot sign on this cluster | [Follow the wallets](#a-wallet-is-not-listed) | | The wallet fails to sign a deposit | It signs only version 0 transactions | [Pass `transactionVersion`](#version-0-and-version-1) | | `misconfigured` from a call | An argument is out of range | [Fix the argument](#misconfigured-from-a-call) | | `recipient-unregistered` from a payment | The recipient has not registered | [Ask them to register](#the-recipient-has-not-registered) | | `fee-payer-unfunded` from a registration or deposit | The wallet holds too little SOL | [Add SOL to the wallet](#the-wallet-cannot-pay-the-fee) | | Every payment fails `unauthorized` | No gateway token, or the gateway refused it | [Pass a token](https://sdk.nimbusprivacy.xyz/getting-started/setup#the-mainnet-gateway-token). To get one, email [dev@umbraprivacy.com](mailto:dev@umbraprivacy.com) or reach out to any Umbra team member. | | A balance does not change | The device has not synced | [Sync, then read](#a-balance-is-not-updating) | ## Not cross-origin isolated `loadNimbusSdk` threw a `NimbusSdkError` with reason `unsupported-browser`. Its message says the page is not cross-origin isolated. **Cause.** The page was served without `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`. Without them, the browser will not share memory with the prover. **Fix.** Send both headers with the page itself, as [Turn on cross-origin isolation](https://sdk.nimbusprivacy.xyz/getting-started/setup#turn-on-cross-origin-isolation) shows. Then run `crossOriginIsolated` in the console. If it still prints `false`, look for a proxy or CDN that drops the headers. ## A file digest mismatch `loadNimbusSdk`, or the first payment, threw `dependency-nonconforming`. The message names a file, its SHA-256, and the SHA-256 this SDK expects. **Cause.** Your app serves a different build of that file than the installed SDK ships. Usually it is left over from an older version, or a cache serves an old copy. **Fix.** Run `nimbus-solana-web copy-assets` again, and run it after every install from now on. Clear any cache in front of the files. [Serve the SDK's files](https://sdk.nimbusprivacy.xyz/getting-started/setup#serve-the-sdks-files) shows the script. ## Stuck at prepared The progress log shows `prepared`, then nothing for a long time. **Cause.** After `prepared`, the payment is proved on the device. The first proof also downloads the circuit files, which can take a while on a slow connection. Later proofs read them from the browser's cache. A browser may also slow a tab that is in the background. **Fix.** Keep the tab open and in front, and tell your user to. If it never moves, open the developer tools. Look for a failed request to the proving key host, or an error from the worker. ## A wallet is not listed `listWallets` returns an empty list, or misses the wallet your user has. **Cause.** `listWallets` reads the wallets installed at the moment you call it. An extension that registers later is missing. A wallet is also left out when it cannot connect, sign messages and sign transactions on the SDK's cluster. **Fix.** Use `followWallets` to keep the list current, as [Use it with React](https://sdk.nimbusprivacy.xyz/getting-started/react#pick-a-wallet) shows. Check that the wallet supports the cluster you loaded, such as `solana:mainnet`. A wallet that does not implement the Wallet Standard cannot be listed. ## Version 0 and version 1 A registration or deposit fails when the wallet is asked to sign it. **Cause.** Payments send version 1 transactions by default. Some wallets sign only version 0. **Fix.** Pass the `transactionVersion` that `openWalletConnection` returned to every call the wallet signs. At version 0, a deposit takes two transactions. The first moves the funds to a second address the SDK derives for your user. The second deposits them from there. [Wallets that sign only version 0](https://sdk.nimbusprivacy.xyz/deposit#wallets-that-sign-only-version-0) covers what to do when only the first lands. ## Misconfigured from a call A call threw `misconfigured` before it fetched anything. The message names the argument. **Cause.** An argument or option is outside what the function takes. For example: - `readHistory`'s `limit` is outside 1 to 100. - `syncNoteStore`'s `pageRows` is outside 1 to 1000, or `maxRounds` is below 1. - A context's `poolIndex` or node index is outside 0 to 65535. - An address is not valid base58. - `resolvePendingDeposit` was given a deposit whose outcome was not `unknown`. - The gateway token is not a valid bearer token. **Fix.** Pass a value in range. Resolve a deposit only when its submission's `kind` is `unknown`. Any other outcome is settled already. ## The recipient has not registered A deposit to another user, or a Private Send, threw a `NimbusSdkError` with reason `recipient-unregistered`. The same reason's partner, `account-unregistered`, means the payer itself has not registered. **Cause.** The recipient's wallet has never registered, so there is no private balance to pay into. Nothing was signed or sent. **Fix.** Ask the recipient to open your app and register. Then try the payment again. Retrying before they register gives the same error. ## The wallet cannot pay the fee A registration, a deposit or a refund threw a `NimbusSolanaFlowError` with reason `fee-payer-unfunded`. **Cause.** The connected wallet pays for these transactions, and it holds too little SOL. A wallet that has never held SOL has no account on Solana at all. The SDK reads its balance before it builds any proof or asks Nimbus to approve. So it throws before the slow steps, and nothing is signed or sent. The amount counts the network fee and any priority fee. A deposit also counts the SOL it moves and the rent of a token account it opens. The wallet must keep Solana's rent-exempt minimum on top. **Fix.** Ask your user to add SOL to the wallet, then try again. The error's `detail.requiredLamports` and `detail.heldLamports` say what it needs and what it holds. A Private Send or a withdrawal never throws this, because the relayer pays for them. ## A balance is not updating The balance does not show a deposit, or a payment someone made to your user. **Cause.** The balance is read from the device, and only a sync brings it up to date. A new deposit also reads as `pending` until Solana finalizes it. **Fix.** Call `syncNoteStore` before `readBalances`. To show payments as they arrive, sync on an interval, as [Use it with React](https://sdk.nimbusprivacy.xyz/getting-started/react#sync-in-the-background) shows. A deposit whose result was `unknown` may not have landed yet. [If the deposit is still pending](https://sdk.nimbusprivacy.xyz/deposit#if-the-deposit-is-still-pending) shows how to settle it. ## Next - [Handle errors](https://sdk.nimbusprivacy.xyz/api-design/results-and-errors): Cover every result and error in one place. - [Browser support](https://sdk.nimbusprivacy.xyz/production/browser-support): What each browser must offer. Last updated 21 October 2026