Failure modes
| Symptom | Cause | Fix |
|---|---|---|
| Page crashes on load | Privy imported at the top of a route | Lazy-load inside <ClientOnly> |
| Secret form rejects the name | VITE_* prefix | Name it PRIVY_APP_ID, read in a route loader |
| Tempo explorer link 404s | Used /tx/<hash> | Use /receipt/<hash> |
| Tempo send reverts | Non-zero value | TIP-20 transfer, value: 0n |
| Tempo send hangs forever | Client transactions disabled in Privy | Enable it; add a 45s timeout |
| "Insufficient funds" with OUSD balance | No gas sponsorship | Enable chain in Privy Gas Sponsorship + sponsor: true |
| Amount off by 10^12 | Hardcoded 18 decimals | Read decimals() / getMint |
| Solana transfer fails "invalid program" | Wrong token program | Use the mint account's owner as program id |
| Solana recipient has no account | Missing ATA | Prepend idempotent ATA create instruction |
| 429 errors | Public RPC rate limit | Server-only RPC secret, proxy via server function |
| Success shown but nothing on explorer | Didn't wait for confirmation | waitForTransactionReceipt / confirmTransaction first |