Troubleshooting

Find the symptom, then read its section below.

Not cross-origin isolatedCopy Anchor Link

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 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 mismatchCopy Anchor Link

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 shows the script.

Stuck at preparedCopy Anchor Link

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 listedCopy Anchor Link

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 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 1Copy Anchor Link

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 covers what to do when only the first lands.

Misconfigured from a callCopy Anchor Link

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 registeredCopy Anchor Link

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 feeCopy Anchor Link

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 updatingCopy Anchor Link

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 shows. A deposit whose result was unknown may not have landed yet. If the deposit is still pending shows how to settle it.

NextCopy Anchor Link