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
Insufficient Turbo Credits: Use --on-demand with --max-token-amount to automatically fund uploads when balance is low
On-demand payment fails: Ensure your wallet has sufficient tokens (ARIO or Base-ETH) and the token type matches your signer (ario with Arweave, base-eth with Ethereum)
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?