Troubleshooting

Causes

MetaMask not installed; wallet locked; unsupported browser; multiple wallet extensions conflicting.

Solutions

Install MetaMask; unlock your wallet; use Chrome, Firefox, or Brave; disable conflicting wallet extensions.

Causes

Your wallet is connected to a different chain than the app expects.

Solutions

Switch the network in MetaMask, or use the chain selector in the app header.

Causes

Groth16 prover failed to load (snarkjs); IndexedDB blocked; proof artifact download failed; slow or interrupted internet connection.

Solutions

Refresh the page. Ensure your browser supports WebAssembly. Disable private browsing mode. Check your internet connection. Try a different browser.

Causes

IndexedDB is unavailable in private browsing on Safari and some Firefox configurations. The RAILGUN engine requires IndexedDB for its merkle tree database and proof artifacts.

Solutions

Use normal (non-private) browsing mode. RAILGUN requires persistent browser storage to function.

Causes

WebAssembly memory limits on mobile; proof generation is CPU-intensive and may exceed available resources.

Solutions

Use a desktop browser for best performance. If using mobile, keep the tab in the foreground during proof generation.

Causes

You clicked "Reject" in MetaMask, or the MetaMask popup was closed before signing.

Solutions

Try again and click "Sign" when MetaMask prompts. The signature is a message signature — it costs no gas and sends no transaction.

Causes

The RAILGUN engine is still initializing, or initialization failed silently.

Solutions

Wait for the "Privacy engine initializing..." message to complete. If it never completes, refresh the page.

Causes

Wallet sync hasn't started yet, or sync is still in progress.

Solutions

Check the sync indicator in the bottom-right corner. Wait for the sync to reach 100% before sending.

Causes

The derived private key is held in memory and not persisted to disk. Each new session requires a fresh signature. This is an intentional security measure.

Solutions

This is expected behavior. Sign in again — your shielded tokens are safe on-chain and will reappear after sync.

Causes

QuickSync endpoint unreachable; RPC provider is down; engine initialization failed before sync started.

Solutions

Check your internet connection. Refresh the page to re-initialize the engine. Try a different network if available.

Causes

First-time sync must process the entire merkle tree history. Mainnet has significantly more history than testnets.

Solutions

This is expected for first sync — it can take several minutes on mainnet. Subsequent syncs only process new blocks and are much faster. Keep the tab open and active.

Causes

The POI node is configured with different list keys than the Wallet SDK expects. This is a backend configuration mismatch.

Solutions

Try refreshing. If persistent, this is a POI node configuration issue that requires updating the node to support the SDK's expected list key.

Causes

The configured POI node is not compatible with the current chain's TXID sync source.

Solutions

Try refreshing. Switch to a different supported chain if available. This is a node compatibility issue.

Causes

Transient merkletree data inconsistency, usually self-resolving.

Solutions

Try scanning again — the app auto-repairs on retry. If persistent, do a hard refresh (Ctrl+Shift+R) to restart the engine from scratch.

Causes

The initial sync on mainnet or Arbitrum exceeded the timeout (2-5 minutes depending on chain).

Solutions

Try scanning again. Progress is saved between attempts — each retry catches up from where the last scan stopped, so it gets faster.

Causes

You haven't shielded tokens yet on this chain; you shielded on a different chain; PPOI is still clearing (balance is in "pending" state, not "spendable").

Solutions

Verify you shielded tokens on this specific chain. Check if there's a "pending" balance — that means PPOI hasn't cleared yet. Wait for PPOI clearance.

Causes

Not enough tokens for the shield amount, or not enough ETH for gas. Shielding can involve up to 3 transactions (wrap + approve + shield), each requiring gas.

Solutions

Reduce the amount. Ensure you have enough ETH to cover gas fees for all transactions.

Causes

You rejected the approval transaction in your wallet; gas was too low; the contract interaction reverted.

Solutions

Try again and confirm the approval in your wallet. Ensure you have sufficient ETH for gas.

Causes

Wrapped token not configured for this chain; insufficient balance to cover both the wrap amount and gas; transaction reverted.

Solutions

Ensure you're on a supported chain. Check that your ETH balance covers both the wrap amount and the gas fee.

Causes

Token approval didn't go through (insufficient allowance); contract error; gas estimation failed.

Solutions

Verify the approval transaction confirmed before the shield. Try again. If gas estimation failed, your wallet may prompt you to set gas manually.

Causes

The RPC provider failed to load for this chain during engine initialization.

Solutions

Refresh the page. Check your internet connection. The provider loads during engine initialization.

Causes

The shared symmetric key for shield encryption couldn't be generated.

Solutions

Sign out and sign in again to re-derive your wallet. If the issue persists, clear your browser data for this site and start fresh.

Causes

PPOI clearance hasn't started yet, or the shielded balance scan hasn't picked up the new deposit.

Solutions

The app scans automatically after shielding. Your balance will appear as "pending" first, then transition to "spendable" after PPOI clearance.

Causes

Mainnet clearance can take up to 60+ minutes. Network congestion or POI node backlog can extend this.

Solutions

This is normal for mainnet. The progress bar shows an estimate. Your tokens are safe in the shielded pool throughout the wait.

Causes

The POI node is down or unreachable, or POI processing failed for this specific deposit.

Solutions

Wait at least the full estimated time (5 min testnet, 60 min mainnet). If still pending after 2x the estimate, the POI node may be experiencing issues. Your tokens remain safe and will become spendable when the node recovers.

Causes

Nothing bad. The pipeline state is saved to your browser's localStorage.

Solutions

Reopen the page. After signing in and waiting for sync to complete, a resume banner will appear. Click "Resume" to continue from where you left off.

Causes

The saved pipeline state expired (mainnet: 24 hours, testnet: 2 hours); you're using a different browser or device; localStorage was cleared.

Solutions

If expired, your tokens are still safe in the shielded pool. Go to /wallet to manage your shielded tokens manually.

Causes

You clicked "Dismiss" on the resume notification.

Solutions

Dismissing does NOT affect your shielded tokens — they remain in the private pool. Go to /wallet to view your shielded balance and unshield manually.

Causes

Your device is slow; the browser tab was backgrounded (browsers throttle background tabs); memory pressure from other tabs.

Solutions

Keep the tab in the foreground and active. Close other heavy tabs. Proof generation is CPU-intensive — it takes 20-30 seconds on modern hardware, longer on older devices.

Causes

Available memory was exceeded; proof artifacts in IndexedDB are corrupted; a browser extension is interfering with WebAssembly execution.

Solutions

Refresh and try again. If the issue persists, clear the site's IndexedDB storage (this forces re-download of proof artifacts). Disable browser extensions that might intercept WebAssembly or network calls.

Causes

Proof generation ran out of memory. This is more common on mobile devices or systems with limited RAM.

Solutions

Use a device with more RAM. Close other tabs and applications to free memory. On mobile, proof generation may exceed available resources — a desktop browser is recommended.

Causes

No broadcasters are currently online for this chain/token combination; Waku network connectivity issue; the broadcaster client couldn't start.

Solutions

Toggle to "Direct send" mode as a fallback (your address will be visible on the unshield). Alternatively, try again in a few minutes — broadcasters come and go. Check that your network or VPN isn't blocking WebSocket connections.

Causes

Waku peer discovery failed; a firewall is blocking the Waku protocol; all discovered broadcasters reported as unavailable.

Solutions

The app auto-reconnects — it monitors peer health every 15 seconds and restarts after 3 consecutive failures. Wait 30-60 seconds and retry. Switch to direct mode if the transaction is urgent.

Causes

Each broadcaster sets their own fee based on gas costs plus a margin. The app selects from available broadcasters.

Solutions

Fees vary by broadcaster. Try again to potentially be matched with a different broadcaster offering lower fees. Direct mode has no broadcaster fee but uses your own gas.

Causes

The unshield delivered WETH (wrapped ETH) to the recipient, but the automatic unwrap to native ETH failed.

Solutions

Your funds are not lost. You have WETH in the recipient's public wallet. It can be unwrapped to ETH manually on any DEX or wrapper interface.

Causes

Gas price was too low for current network conditions; the network is congested.

Solutions

Wait — the app polls for the receipt with exponential backoff. If stuck for more than 10 minutes, the transaction may need to be sped up in MetaMask (increase gas price on the pending transaction).

Causes

A typo or incorrect address was entered in the recipient field.

Solutions

Blockchain transactions are irreversible. Always double-check the recipient address before sending. The app validates address format (0x + 40 hex characters) but cannot verify the intended recipient.

Causes

The token is not in the default token registry for this chain, or it's a very new or custom token.

Solutions

The token list is loaded from on-chain registry data. If your token doesn't appear, it may not yet be supported on this chain's RAILGUN deployment.

Causes

Wallet not connected; wrong chain selected; balance fetch failed; tokens are in the shielded pool (not public balance).

Solutions

Connect your wallet. Verify you're on the correct chain. Check both "public" and "shielded" balances — tokens in the pool won't show as public. Trigger a manual refresh.

Causes

Tokens in the shielded pool don't appear as public wallet balance because they're held by the RAILGUN contract.

Solutions

Public balance = tokens in your 0x wallet. Shielded balance = tokens in the RAILGUN pool controlled by your private key. Shielded "pending" = waiting for PPOI clearance. Shielded "spendable" = ready to use for private transactions.

Causes

PPOI clearance hasn't completed yet, or there's a POI node issue.

Solutions

See the PPOI Clearance section above. Pending tokens will transition to spendable after PPOI completes.

Causes

RAILGUN only works with ERC-20 tokens. Native ETH is automatically wrapped to WETH for shielding, and unwrapped back to ETH on unshield.

Solutions

This wrapping/unwrapping is handled automatically by the app. If the auto-unwrap fails on the recipient side, WETH can be manually unwrapped to ETH on any DEX.

Causes

The transaction is still pending; the recipient is checking the wrong chain; the recipient is checking the wrong address; block explorer indexing delay.

Solutions

Verify the unshield transaction hash on a block explorer. Confirm the recipient is checking the correct chain and wallet address. Block explorers may take 1-2 minutes to index new transactions.

Causes

The simplified send operation was interrupted; the resume banner was dismissed; PPOI is still clearing.

Solutions

Go to /wallet — the wallet interface lets you view shielded balances and manually trigger unshield transactions.

Causes

The simplified send flow was interrupted or dismissed before completing.

Solutions

Use the /wallet page: sign in, wait for sync to complete, select the shielded token, and use the unshield action.

Causes

No. Tokens are on-chain in the RAILGUN smart contract, not in your browser.

Solutions

Sign in again with the same wallet (same signature). Wait for sync to complete. Your shielded balances will reappear as the merkle tree is re-scanned.

Causes

The Waku P2P protocol or RPC endpoints are being blocked by your network configuration.

Solutions

Try without VPN. Ensure WebSocket connections are allowed. The broadcaster relies on the Waku network (which uses libp2p) — some corporate firewalls and VPNs block this.

Causes

Browser extensions are blocking WebAssembly execution, RPC calls, or Waku connections.

Solutions

Disable ad blockers and privacy extensions for this site. Whitelist the RPC and Waku domains. Consider using a dedicated browser profile with minimal extensions.