Deploy issues

When the deploy goes wrong — preflight fails, build crashes, URL is dead.

Deploy fails at preflight

The Deploy button shows "preflight build failed in the sandbox before reaching the build step".

This is by design. Preflight runs npm run build (or your stack's equivalent) before shipping. A failure here means the project doesn't compile — fix it in the source sandbox.

The verbatim compiler output is right there in the failure message. See Build failures for common error shapes.

Deploy fails at "Build"

Preflight passed; the actual container build failed.

Most common causes:

• Native dependency that doesn't compile in the build image. Some Node packages (sharp, canvas, node-gyp things) need system libraries the build image doesn't include. Solution: pre-compile binaries into your repo, or use a different package.
• Lockfile mismatch. If your project has more than one lockfile, the build can pick the wrong package manager. Commit a single lockfile that matches the package manager you use (e.g. just package-lock.json), or drop a Dockerfile in the project root to control the build exactly.

If you see "no installable manifest detected" in the build logs, the build context didn't include the right files. Confirm the project is at /workspace/projects/<name>/ and has a package.json (or equivalent) at its root.

Deploy succeeds but URL returns 404

The container started, but the URL serves 404.

Common causes:

• App is listening on the wrong port. The container's env has PORT=3000 by default. If your app listens on 8080 instead, requests miss. Either:

  • Change your app to read process.env.PORT.
  • Override PORT in the deployment Env tab to match what your app uses.

• Static export with no fallback. Next.js output: 'export' creates static HTML; deep links 404 if there's no matching file. Either drop the export config, or add a 404 page, or use a real Next.js server build.

• App crashed at startup. Container shows as Running because Docker is restarting it. Check the logs (deployment detail page → Logs).

Deploy succeeds but URL returns 500

The app is up but throwing errors.

First stop: deployment detail page → Logs. The stack trace tells you exactly which file + line is throwing.

Common 500 causes:

• Missing env var. The app references process.env.SOMETHING that wasn't set in the deployment's Env. Add it and redeploy.
• Database not reachable from the container. Your bound DB URL points at a host the production container can't reach (e.g. localhost from a remote server, or a dev DB blocked by a firewall). Override MONGODB_URL in the deployment Env with a prod URL.
• Build-time vs runtime env mixup. A server-side route reads process.env.X but X was only set as NEXT_PUBLIC_* (or vice versa). Pick one and match the call site.

Deploy succeeds but URL is intermittent

Sometimes 200, sometimes 502. Tunnel health indicator shows amber.

See Connection + tunnel troubleshooting. Most likely the server's tunnel is flapping.

Container OOMKilled

The container starts, takes traffic for a few minutes, then gets killed by the OOM killer. New container starts, same fate.

Cause: the app is using more memory than the container has.

Fix: bump container resources at deploy time. Deployment detail page → Resources → increase memory cap.

Or fix the leak in the app — if you don't expect to need 8GB for a simple Node server, you probably have a memory issue (unbounded array, leaked event listeners, etc.). Use Node's heap snapshot tools to find it.

"image pull failed"

The deploy got to the Push phase but the image isn't available when Run tries to pull it.

This is rare — but if you see it:

• Confirm the server's Docker daemon is healthy: docker info over SSH.
• Confirm disk space: df -h /var/lib/docker.
• Restart the deployment from the dashboard. If it persists, escalate.

"deployment already exists"

You clicked Deploy with the same name twice within seconds.

The first deploy is still in progress. Wait for it to finish, then either redeploy (if you want the new code) or leave it (if the first one is what you wanted).

Cleanup: deployments piling up

Each deploy keeps the previous container image on the server. Over many redeploys this can fill disk.

Cleanup:

ssh your-server
docker image prune -a -f

This removes images not referenced by any container. Running deployments keep their images; stopped or failed deploys' images get reclaimed.

Cleanup: orphaned deployment rows

You deleted a sandbox but its deployment still exists in the dashboard.

This is intentional — deployments outlive their source sandbox. If you don't need the deploy:

• Dashboard → deployment → Stop → Delete.

Redeploy is slower than I expect

First deploy of a project: 60-120 seconds is normal.

Subsequent deploys should be much faster (cache hit) — usually 20-40 seconds. If they're not, the build cache is missing.

Possible reasons:

• package.json changed. Any dep change invalidates the install layer.
• Disk pressure caused old layers to be reaped.
• You're deploying from a different sandbox (each sandbox has its own image cache namespace).

Nothing to "fix" — these are correct invalidations. If you want consistent fast redeploys, stick with one source sandbox per deployment.

When the deploy is fine but the world thinks it's broken

Sanity-check the URL itself:

curl -sI https://your-app-xxxx.agentry.live
# HTTP/2 200
# ...

If that returns 200 from your terminal but users say they see errors:

• They might be on a stale DNS cache. Have them try in a fresh browser / incognito.
• They might be hitting a CDN cache (if you've put one in front). Purge it.
• They might be seeing a different URL than you intend. Double-check what you shared.

Next

• Build failures — preflight failures in detail.
• Connection issues — when the tunnel is the issue.
• Logs + status — the dashboard surfaces.