Troubleshooting

The most common problems, each with why it happens, how to fix it, and how to avoid it next time. For CLI-specific issues (login loops, token errors, repo matching), see CLI Troubleshooting.

AI fix prompt

When a deployment fails, the failure email includes an AI diagnosis of the likely cause and a copy-paste prompt for Cursor, Claude Code, or Copilot that contains everything needed to fix the repo — the detected stack, the error, and the relevant log tail. Pasting it into your AI coding tool is usually the fastest path to a fix.

Why it happens#

When the OAuth exchange with GitHub fails, you are redirected back to the site with ?auth=failed in the URL. Typical causes: the authorization was denied or timed out on GitHub's side, browser extensions or strict privacy settings blocked the redirect, or a stale session interfered with the callback.

How to fix#

Retry the sign-in — transient OAuth failures are the most common case.
Disable aggressive content/cookie blockers for deplo.in and github.com.
Try a private window to rule out stale state, then sign in normally.

Prevention#

Complete the GitHub authorization promptly when the popup appears, and keep deplo.in out of your blocker's strict list.

Private repositories not appearing#

Why it happens#

OAuth sign-in covers listing and reading your public repositories. Private repositories additionally require installing the deplo GitHub App, which grants explicit per-repo access.

How to fix#

Open Dashboard → Repositories — when a private repo needs the App, the dashboard shows an install prompt. Install the App, select the repositories you want deployable, then hit Sync.

Prevention#

When installing the App, grant access to all repositories you plan to deploy (you can change the selection later in GitHub → Settings → Applications).

Build fails on the provider#

Why it happens#

The two dominant causes are:

Wrong root directory — the app lives in a subfolder the detection engine could not attribute (unusual layout, several apps in one folder).
Missing or broken scripts — Node builds run your repo's own package.json scripts. If build or start is missing, broken, or depends on tools that only exist on your machine, the provider build fails.

How to fix#

Open the deployment's log page — the full provider log is there, followed by the AI diagnosis: likely cause, suggested corrected build/start commands, and a recommendation.
Use the fix prompt from the failure email in your AI coding tool, push the fix, and redeploy.
Verify locally first: npm run build and npm start must work from a clean clone.

Prevention#

Follow the layout and script conventions in Best Practices — one app per folder, working build/start scripts, lockfile committed.

Deployment stuck in WAITING_FOR_ENV#

Why it happens#

This is not an error — the analyzer found required environment variables with no value, parked the deployment, and emailed you the exact list of missing keys. Nothing deploys until they are provided.

How to fix#

Provide the values on the deployment page (or via POST /api/v1/deployments/:id/env, or the CLI prompts). The deployment resumes immediately. If a variable is genuinely unused, remove the reference from your code — required-ness comes from what your code reads.

Prevention#

Pre-fill values on the Configure step before deploying, or keep an up-to-date .env.example with safe defaults so fewer variables are strictly required. See Environment Variables.

Invalid Render API key#

Why it happens#

Render keys are validated live against the Render API before being stored — an invalid key is rejected immediately and never saved. A key that worked before can also stop working if you revoked it in Render or deleted the workspace it belonged to.

How to fix#

Create a fresh key in Render → Account Settings → API Keys — it starts with rnd_.
Paste it in Dashboard → Integrations using the rotate flow — reconnecting with a new key replaces the old one.

Prevention#

If you rotate keys in Render as routine hygiene, update the Integrations page in the same sitting — backend deploys and live server metrics both depend on it.

Vercel not connected#

Why it happens#

Frontend deployments need the deplo.ai Vercel integration authorized on your account. If you skipped that onboarding step, or uninstalled the integration from your Vercel dashboard (deplo.ai detects the uninstall and marks the connection removed), deployments with a frontend fail with a “connect Vercel” error.

How to fix#

Open Dashboard → Integrations and connect Vercel — it is a one-click OAuth flow. Backend-only repositories are unaffected; they deploy with Render alone.

Prevention#

Complete both provider connections during onboarding, before your first full-stack deploy.

Deployment failed, but the old site is still up#

Why it happens#

This is by design. A failed attempt never touches what is already serving traffic — the live URLs always belong to the latest successful deployment. So a red failed deploy and a perfectly healthy production site coexist.

How to fix#

Open Project monitoring & analytics: the latest-attempt banner shows the failed attempt and its error, while the uptime charts below confirm the previous successful deploy is still live. Fix the failure (see the AI diagnosis), redeploy, and the new version replaces the old one only when it completes. See Monitoring & Analytics.

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 200
RateLimit-Remaining: 0
RateLimit-Reset: 412

Still stuck?#

CLI Troubleshooting — login loops, token errors, repo matching.
Deployment Lifecycle — what every status means.
FAQ — billing, providers, and security questions.