Guide/Reference
✓ Reviewed August 2026
Reference
7 Issues

Troubleshooting

Diagnose and fix the most common deployment issues.

🔴 Problem: App doesn't work
Is the page blank?
YES
Check index.html → add <script> tag
NO
Do AI features fail?
Check Vercel env variables (all 4)
Can't install on Android?
Check manifest.json exists and is valid
✅ Problem resolved — check browser console for other errors
Symptoms
  • App works in AI Studio's preview but shows a blank page on Vercel
  • Browser console: "Failed to load resource" errors
Fix
  • Go to GitHub → open index.html → check that <script type="module" src="/index.tsx"></script> is inside <body>
  • If missing, edit on GitHub, add it back, and commit
  • Verify index.tsx or main.tsx exists in the repo root
  • Check Vercel's build logs (Deployments tab) for the specific error
Symptoms
  • App loads but AI features don't work
  • Error messages about the API key in the browser console or network tab
Fix
  • Vercel → Your Project → Settings → Environment Variables
  • Verify the variables your code actually reads exist — commonly GEMINI_API_KEY, API_KEY, VITE_API_KEY, and GOOGLE_GENERATIVE_AI_API_KEY
  • Regenerate the key in AI Studio if needed, and update every variable that holds it
  • Redeploy: Vercel → Deployments → ⋯ → Redeploy
Common Errors
  • "Cannot find module 'vite'" → ensure package.json includes all dependencies
  • "Build command failed" → build command must match your project, usually npm run build
  • "Memory limit exceeded" → simplify the app or remove large dependencies
Fix
  • Click the failed deployment in Vercel and read the error log carefully
  • Fix the specific error in your GitHub repository and commit — Vercel auto-redeploys
Symptoms
  • No "Install app" prompt appears in Chrome
  • "Add to Home Screen" is greyed out
Fix
  • Verify manifest.json exists in the root of your GitHub repo
  • Confirm index.html has <link rel="manifest" href="/manifest.json">
  • Use Chrome specifically — support is most consistent there
  • Check Chrome DevTools → Application → Manifest tab for errors
  • Your Vercel URL must use HTTPS (it does by default)
Fix
  • Force refresh: open app → pull down to refresh, or close and reopen
  • Clear app cache: Android Settings → Apps → Your App → Storage → Clear Cache
  • Reinstall: uninstall, visit the Vercel URL in Chrome, reinstall a fresh copy
Fix
Symptoms
  • A key you haven't used in a while shows a "Blocked" tag on the AI Studio API Keys page
  • Requests using that key start failing with an authorization error
Fix
  • Google now blocks unrestricted API keys that sit dormant for an extended period as a security measure
  • Open the AI Studio API Keys page and click Create API key to generate a new one — new keys are created with the current recommended restrictions automatically
  • Update every environment variable that referenced the old key, in Vercel and anywhere else it's used, then redeploy
← Part 6Update Workflow