Debug a failed web app deployment

Start with the deployment status

Open your app's deployment history first. The status usually tells you which layer to inspect: source build, rollout, startup, health checks, or runtime behavior after deploy.

• Build failed: inspect build logs.
• Deploy failed after build: inspect runtime logs, health checks, and runtime settings.
• App is live but unhealthy: inspect health check path, start command, env vars, CPU, and RAM.

If the build failed

Build logs show dependency install, compile, framework build, and source packaging output. The most useful error is often near the last failing command.

• Confirm the lockfile is committed, such as bun.lock, package-lock.json, or pnpm-lock.yaml.
• Check that the root directory contains the app's package.json, go.mod, requirements.txt, or equivalent project file.
• Set explicit install and build commands if automatic detection picked the wrong commands.
• Reduce install/build work if the app approaches the 25 minute build timeout.

If the app built but did not start

Runtime logs show stdout/stderr from the current running replica. Use them when the app builds successfully but crashes, exits, or cannot connect to required services.

• Confirm the start command is correct for production.
• Make sure the app listens on the PORT environment variable.
• Check missing env vars like DATABASE_URL, API keys, cache URLs, and secrets.
• Increase memory if the process is killed or exits during startup.

If health checks failed

If no health check path is set, Shiprr uses a TCP check on the app port. If you set a local path like /health, Shiprr uses an HTTP readiness check against that path.

• Use a fast endpoint that does not require login.
• Return a 2xx status when the app is ready.
• Avoid checking slow upstream services unless they are required for startup.
• Check the start command and port binding if every health check times out.

If configuration is missing

Go to App → Settings → Environment variables and review required values. Saving env vars redeploys the app so new values apply to live replicas.

DATABASE_URL=postgres://...
REDIS_URL=redis://...
NODE_ENV=production
PUBLIC_SITE_URL=https://example.com

Keep secrets out of logs. If a build or app process prints a secret, it can appear in build or runtime logs.

If the app works but the domain does not

First test the default Shiprr hostname. If that works, inspect the custom domain setup.

• Confirm the domain is attached to the correct app.
• Confirm DNS points to the Shiprr custom-domain target shown in the dashboard.
• For Cloudflare, keep the record DNS-only during initial setup, then use Full (strict) SSL mode if proxying later.
• Give HTTPS a minute or two to finish issuing after DNS is correct.

If the release should be reverted

Roll back from deployment/build history when a previous successful build is known good. Shiprr reuses that build, skips a source rebuild, and creates a new deployment attempt with current runtime settings.

Rollback does not restore database contents, external services, old env var snapshots, or old domain/routing configuration snapshots. Treat database migrations separately.