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', your Dockerfile is missing a system-level package. Add an apt-get install step (Debian/Ubuntu) or apk add (Alpine) before the language-level install.

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).
• Use a multi-stage Dockerfile — do the heavy build in a builder stage, copy only the artefacts to a slim runtime.
• 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. Exposed port mismatch. If your Dockerfile does EXPOSE 8000 but Project Settings says 3000, the proxy sends traffic to the wrong port. Match the two.

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 for a hardcoded ENV in your Dockerfile — that wins over PreviewDrop's injection.
• Check for a branch override on the variable — overrides win over defaults.

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 (1 hour 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.