Troubleshooting

Sign-in / wallet errors

"Authentication required"

What it means: Your engine session has expired or wasn't issued.

Fix: Click the auth badge in the top-right (it'll say Try Again) and re-sign the challenge message. Sessions last ~1 hour; if you took a long break between page loads, you'll need to re-sign.

"Wallet not connected"

What it means: Either you signed out, your wallet extension is locked, or the page lost the connection.

Fix: Click Sign in with Google or your wallet button in the top-right. If the wallet extension shows as locked, unlock it from the browser toolbar first.

Auth badge stays "Try Again" after I sign

What it means: The signature verified locally but the engine couldn't store the session (Redis hiccup or engine restart).

Fix: Try once more. If it persists, the engine may be down — check the status page or wait a few minutes. The dapp will work on cached data in the meantime but can't upload.

"Please sign in with your wallet" (during upload)

What it means: You tried to upload without a valid session token.

Fix: Same as "Authentication required" — click the auth badge, re-sign.

---

Upload errors

"Upload token request denied (401)"

What it means: The engine rejected your session token for the new-RPC upload path. Usually the session expired between the Configure step and clicking Upload.

Fix: Re-sign (auth badge), then click Upload again. No need to redo the wizard.

"Upload token request denied (429)"

What it means: Your file is over the per-upload size cap (currently 512 MiB).

Fix: Files larger than 500 MiB should auto-route through the direct-to-node path. If you see 429 on a smaller file, the limit was tightened — contact support.

"Walrus upload failed (4xx)"

What it means: The publisher rejected the bytes. Usually a malformed body or a CORS / network issue.

Fix:

• Reload the page (Cmd+Shift+R) to pick up any new client code
• Check the Network tab for the specific status code
• If it's CORS, the publisher's nginx config needs updating — contact support

"No blob ID returned from Walrus publisher"

What it means: The publisher accepted the bytes but the response was malformed or empty.

Fix: Retry once. If it persists, the publisher infra has a problem.

Upload stalls at ~80%

What it means: Publisher returned, but the wallet popup for the on-chain register transaction was blocked or dismissed.

Fix: Check your wallet extension — there may be a pending signature request. Approve or reject it explicitly. Don't navigate away during this state; the wizard is waiting.

Multi-file: same blob ID appears N times

What it means: Fixed in latest release (a stale-state bug in the multi-file separate loop).

Fix: Hard refresh (Cmd+Shift+R) to pick up the latest client code. If you're on the latest and still see this, file a bug.

"Wallet not connected" mid-upload

What it means: Browser extension state desynced from the page during a long upload.

Fix: Reload, re-sign, retry. If you're on a long-running multi-file batch and one file fails this way, the wizard stops cleanly — earlier files are already on-chain and safe.

---

SEAL / encryption errors

"SEAL decrypt failed"

What it means: One or both key servers refused to release a key share, or the network couldn't reach them.

Fix:

• Are you the owner or a viewer of this blob? Check the Sharing page. If you're neither, decryption is denied (as designed).
• Is your session valid? SEAL needs a fresh wallet signature. Click the blob again to retry; it should trigger a wallet popup.
• Key server down? Check the network tab — if one returns 500 or times out, wait a few minutes.

"Session key expired" when opening an encrypted blob

What it means: Your SEAL session signature (separate from your engine session) has aged out.

Fix: Click the blob again; the dapp will prompt for a fresh wallet signature. SEAL sessions last ~1 hour.

"SealNotInstalledError" (SDK)

What it means: You're using the SDK and tried to encrypt/decrypt without @mysten/seal installed.

Fix: bun add @mysten/seal. See the SDK docs.

---

Subscription / payment errors

"Insufficient USDC balance"

What it means: Your wallet doesn't hold enough testnet/mainnet USDC for the subscription transaction.

Fix:

• Testnet: grab USDC from the Sui testnet USDC faucet (linked from Plans page)
• Mainnet: buy USDC on a Sui DEX (Cetus, Aftermath) or bridge from another chain

"Plan not switching after upgrade"

What it means: Transaction landed but the dapp's cache is stale.

Fix: Wait ~5 seconds for the indexer to catch up, then refresh the page. If still wrong after 30 seconds, the Sui transaction may have failed — check the Plans page's transaction history (or your wallet's history).

"Subscription expired but I can still upload"

What it means: You're in the grace period (a few epochs after expiry). After grace ends, uploads start to fail.

Fix: Click Renew on the Plans page to restore the active state.

"Pending downgrade won't cancel"

What it means: The cancel-downgrade transaction was rejected or hasn't landed yet.

Fix: Try the "✕ Cancel downgrade" button again. If it keeps failing, check the wallet for a stuck transaction.

---

Connector errors

"Connection failed (S3 / GCS / Azure)"

What it means: Credentials are wrong, missing permissions, or the bucket name / region doesn't match.

Fix:

• Verify credentials in the source console (AWS / GCP / Azure)
• Confirm the IAM/service-account/SAS policy includes read and list on the target bucket
• Re-check the bucket name and region (case-sensitive)

"OAuth loop" (Google Drive / Dropbox)

What it means: OAuth callback came back but the dapp didn't persist the token, so the next click triggers OAuth again.

Fix:

• Make sure third-party cookies are allowed for the dapp domain
• Try disconnecting from Settings → Connected accounts, then reconnect
• If it still loops, the OAuth client config may have rolled — contact support

"SFTP connection refused"

What it means: Host/port unreachable, or auth failed.

Fix:

• Confirm the host accepts SFTP (port 22 is standard but some boxes use 2222)
• Test the same credentials from your local terminal (sftp user@host)
• If it works locally but fails in the dapp, the dapp's server IPs may need to be allowlisted at the destination

---

Files / History errors

"File missing in History"

What it means: The on-chain register transaction may have failed silently, OR the indexer is slow.

Fix:

• Refresh after 30 seconds
• Check the wallet's transaction history for a register_blob call
• If the tx isn't there, the upload's final step failed — re-upload the file

"Files tab is empty but I know I uploaded"

What it means: Wallet connected to a different address than when you uploaded.

Fix: Look at the wallet address shown top-right — does it match the one you used originally? If not, switch wallets (in your extension) and the Files list will populate.

"Cannot fetch blob from aggregator"

What it means: Walrus aggregator returned 404 (blob expired) or 500 (transient).

Fix:

• Check the blob's Health in Files. If it's been expired, the bytes are gone.
• If health is good and you still get errors, retry — the aggregator occasionally hiccups under load

---

Misc

"Transaction failed: out of gas"

What it means: Your wallet doesn't hold enough SUI to pay for the transaction's gas (separate from USDC for subscriptions).

Fix: Send some SUI to your wallet — 0.1 SUI covers ~50 transactions. Sui testnet faucet for testnet.

Dapp pages won't load (white screen)

What it means: Client-side JavaScript error, often after a deploy.

Fix: Hard refresh (Cmd+Shift+R). If it persists, open DevTools → Console and screenshot whatever error appears — share with support.

"Pricing not loaded yet"

What it means: The dapp couldn't read the on-chain PlanRegistry. Usually a transient RPC issue.

Fix: Refresh after 10 seconds. If persistent, the Sui testnet RPC is down — try a different RPC URL in the network selector.

Still stuck?