Troubleshooting — Common Errors and Fixes

Common problems and how to fix them. If you don't find your issue here, check the build logs first — they contain the exact error.

Reading Logs

Before trying anything else, check the logs:

• Build logs — Project → Deployments → [deploy] → Build Log
• Runtime logs — Project → Logs — stdout/stderr from the running container
• System logs — SSH into your server: journalctl -u temps -f

# Stream runtime logs via CLI
bunx @temps-sdk/cli runtime-logs --project my-app --follow

# View last 100 lines
bunx @temps-sdk/cli runtime-logs --project my-app --tail 100

Build Errors

npm install fails — ENOTFOUND or registry timeout

The build container can't reach the npm registry:

1. Check outbound internet access: curl -I https://registry.npmjs.org
2. If behind a firewall, add the registry to the allowlist
3. Consider a private registry or caching proxy

Cannot find module after install

A package listed in devDependencies is used at runtime — move it to dependencies. Or your .dockerignore excludes files that are needed at runtime.

Build exceeds memory limit

# Increase Node.js heap in the build step
RUN NODE_OPTIONS="--max-old-space-size=4096" npm run build

Or increase the limit under Project → Settings → Build Resources.

Multi-stage build — COPY --from file not found

The source path must match exactly what the builder stage produced. Add RUN ls /app in the builder stage to verify paths.

Deployment Errors

Container starts then immediately exits

The container is crashing on startup. Check runtime logs. Common causes:

• Missing environment variable — app throws on startup if a required var is absent
• Port mismatch — app binds to 127.0.0.1 instead of 0.0.0.0
• Wrong start command — CMD in the Dockerfile doesn't match your entry point

Health check failing

1. Check Project → Logs for startup errors
2. Temporarily disable the health check to confirm the app starts at all
3. Ensure the health check path exists and doesn't require authentication

Deployment stuck at "Waiting for container"

# Redeploy via CLI
bunx @temps-sdk/cli deploy --project my-app

Runtime Errors

502 Bad Gateway

The proxy can't reach your container:

• Container crashed — check logs for a panic or uncaught exception
• App is listening on the wrong port — ensure PORT env var is used and bound to 0.0.0.0
• Out of memory — check Project → Metrics for OOM restarts

504 Gateway Timeout

Container reachable but not responding within 30s:

• Slow database query — enable slow query logging and add indexes
• External API call blocking the event loop
• CPU-bound work on the main thread — offload to a worker

Environment variables not updating

Variables set after the last deploy are not live until you trigger a new deploy.

SSL / Domain Issues

Certificate not provisioning

Let's Encrypt requires port 80 to be publicly reachable for the HTTP-01 challenge:

1. Confirm DNS A record points to the correct server IP
2. Test port 80: curl -I http://yourdomain.com
3. Ensure no CDN is intercepting with full-proxy mode enabled

Retry from Project → Settings → Domains → [domain] → Retry.

ERR_TOO_MANY_REDIRECTS

Your app is issuing an HTTP redirect when the proxy already handles HTTPS. Trust the X-Forwarded-Proto header:

// Express
app.set('trust proxy', 1);

DNS not propagating

Propagation can take up to 48 hours (usually under 10 minutes with a low TTL). Check at dnschecker.org.

"No deployment is routed to this host" (branded 404)

If you open a domain and see a Temps-branded page titled "No deployment is routed to this host" with a DEPLOYMENT_NOT_FOUND · 404 chip, the proxy received your request but no app is bound to that host. The page shows the requested Host and a Request ID for support log correlation.

This is expected in two situations:

• DNS still propagating — you just pointed a domain at the server, but the host isn't yet associated with a deployment. Add the domain under Project → Settings → Domains (see Add a custom domain) and wait for propagation.
• Hitting the server by an unrecognized hostname — for example the raw server IP or a stale CNAME. The proxy serves this 404 specifically when the host has no route and the request comes from a non-admin client (the admin gate keeps the management console invisible from such hosts).

The response is HTTP 404 with these headers:

When filing a support request, include the Request ID from the page (or the X-Request-ID response header) — it matches the proxy log line admin gate denied request to non-admin host. To fix it, confirm the domain is added to a project and that DNS resolves to your server.

Database Issues

Connection refused to localhost:5432

Your app is connecting to localhost but the database is in a separate container. Use the internal service hostname from your Temps-provided connection string instead.

Too many connections

Each replica opens its own pool. With many replicas, you exceed PostgreSQL's max_connections (default 100). Reduce pool size per replica:

const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });

Or add PgBouncer as a connection pooler.

Getting More Help

# Run diagnostics
temps doctor

Post in the Discord community with the diagnostics bundle attached.