Troubleshooting

Build failed

Missing dependencies

If the build log ends with something like E: Unable to locate package libpq-dev or ModuleNotFoundError: No module named 'psycopg2', the build is missing a system-level or language-level package. Make sure the dependency is declared in your manifest (requirements.txt, Gemfile, package.json), and prefer pure or binary wheels where one exists (e.g. psycopg2-binary). If the detected install step is wrong, set a custom Install command in Project Settings.

Out of memory during build

Symptoms: build stops abruptly, logs end mid-step, sometimes with killed or exit code 137. Happens on Free (2 GB build limit) with heavy frontend bundlers (webpack, Next.js) or Rails asset precompile.

• Upgrade to Starter (4 GB) or Pro (8 GB).
• For Node, set NODE_OPTIONS=--max-old-space-size=3072 in your env vars.

Build succeeds but runtime errors

Common causes: the container exits immediately (check Runtime logs for the stack trace), or the container starts but your app throws on boot. Usually an env var is missing — PreviewDrop will run the container with whatever you have in the Variables tab.

Preview shows 502 Bad Gateway

PreviewDrop routed traffic to your container but your app didn't respond. Check in order:

1. Binding to the right port. Your app must listen on the PORT env var, not a hardcoded number.

   Fixes
   # Wrong
   app.listen(3000)
   
   # Right
   app.listen(process.env.PORT, '0.0.0.0')

2. Binding to 0.0.0.0, not 127.0.0.1. 127.0.0.1is container-local — PreviewDrop's proxy can't reach it.
3. App hasn't finished booting. Rails and Spring Boot can take 30+ seconds to boot. Watch Runtime logs; if you see Listening on 0.0.0.0:..., the 502 should clear on the next request.
4. Hardcoded port. Traffic goes to the port in the PORT variable. If your start command hardcodes 8000 (or sets its own PORT), the proxy can't reach the app. Use $PORT.

Deployment stuck in building

If a build runs longer than expected:

• Click into the build log — nine times out of ten it's still doing real work (e.g. bundle install compiling native extensions).
• If the log hasn't moved in 10+ minutes, click Cancel and Redeploy. Usually a transient daemon hiccup.
• Builds time out at 20 minutes by default. If yours needs more, contact support — we'll raise the limit for your project.

Environment variables aren't applied

Variables are injected at container start, not hot-reloaded. After you add or change a variable:

• Click Redeploy on the deployment you want updated (or wait for the next push).
• Check that your start command or app config doesn't hardcode the value — that wins over PreviewDrop's injection.

More in Environment variables.

Preview was ready and is now 404

The preview hit its lifetime and was reaped. Previews expire after a window of no traffic (4 hours on Free, longer on paid plans). Push a new commit or click Redeployto bring it back — PreviewDrop rebuilds from the same commit SHA, so you won't lose state that lives outside your container.

Webhook isn't triggering deploys

If you pushed a commit and no new deployment appeared:

• Check Admin → Logs for a webhook.received entry. If there's none, the webhook never arrived.
• On GitHub: open your repo → Settings → Webhooks → PreviewDrop App → Recent Deliveries. Red/orange triangles mean the webhook was rejected. Click one to see the exact response.
• If deliveries show 401: PreviewDrop rotated the signing secret. Uninstall and reinstall the GitHub App (it takes 30 seconds).
• If the commit has [skip preview]in its message, that's intentional — remove it to trigger.

PR comment didn't appear

• Confirm Post preview URL to PRs is enabled in Project Settings.
• Confirm the GitHub App has Pull requests: Write permission (it's granted by default; you may have revoked it).
• Some orgs block external App comments via branch protection. Check your org settings.

Still stuck?

Open an issue or email support@previewdrop.dev with:

• Deployment ID (it's in the URL of the deployment page: .../deployments/dep_xyz).
• A one-line description of what you expected vs what happened.
• Anything suspicious from the Build or Runtime logs.

We reply to every email — usually within a few hours during work hours.