Troubleshooting

Error: "DEPLOY_KEY environment variable not set": Verify your base64 encoded wallet is set as the DEPLOY_KEY environment variable
Error: "deploy-folder does not exist": Check that your build folder exists and the path is correct
Error: "deploy-file does not exist": Check that your build file exists and the path is correct
Error: "ArNS name does not exist": Verify the ArNS name is correct and exists in the specified network
Upload timeouts: Files have a timeout for upload. Large files may fail and require optimization
"402 Payment Required" (or "Turbo refused the upload as unpaid"): The upload service will not take the files for free and no credits cover them. Free uploads are up to 105 KiB per file and 10 MiB over the lifetime of a wallet and of an IP range, so a wallet with allowance left can still be refused when its IP range has used up its own. Add Turbo credits at https://turbo.ardrive.io, re-run with --on-demand and --max-token-amount, or have credits shared to the wallet. Do not use --dev to get around it: a sandbox upload is not permanent. Files that uploaded before the failure are cached, so a re-run does not pay for them again
Insufficient Turbo Credits: Use --on-demand with --max-token-amount to automatically fund uploads when balance is low
On-demand payment fails: Ensure the upload wallet holds the token, and that the token matches the key: ario, solana or solana-usdc with --sig-type solana; base-eth or base-usdc with an Ethereum or Polygon key
"Insufficient Turbo credits" on the sandbox with valid sandbox credits: Use --dev, or pass --payment-url https://payment.services.ar-io.dev with a custom --uploader, so the balance is read from the sandbox
Credits shared with you are not used: They are used automatically unless --ignore-approvals is set; with --paid-by, only the listed wallets count
Deep links 404 but the homepage loads: The manifest has no fallback. Emit a 404.html or pass --fallback-file index.html — see Single-page apps
Deep links still 404 right after a redeploy: Gateways cache the previous manifest's 404s for around a minute. Retry with a cache-busting query string before assuming the deploy failed
Error: "Fallback file not found in folder": --fallback-file takes a path relative to the deploy folder, e.g. index.html, not ./dist/index.html

How is this guide?