Health Check Failures

Your deployment built successfully and the container started, but the health check timed out. The deployment is stuck at HEALTH_CHECKING and eventually fails. Here’s how to debug it.

Step 1: Check the logs

Open the deployment in the dashboard and go to the Logs tab. Look for:

• Application startup errors — Exceptions, missing config, or crash messages.
• Port binding messages — Your app should log which port it’s listening on. Compare this to the port configured in service settings.
• “Listening on…” — If you see this message, the app started. The issue is likely a port or path mismatch.

If the logs show nothing (empty), the container probably crashed immediately. See Container Crashed.

Step 2: Verify the port

The most common cause of health check failures is a port mismatch. Clank probes http://container:{port}{path}. If your app listens on port 3000 but the service is configured for port 8080, the probe gets “connection refused.”

Framework	Default port
Node.js / Express	3000
Next.js	3000
Python / Flask	5000
Python / Uvicorn	8000
Go	8080
Ruby / Rails	3000

Fix: Update the port in your service settings to match what your app actually listens on.

Step 3: Verify the health check path

Clank sends a GET request to the configured path. If the path doesn’t exist, you’ll get a connection that works but no successful response.

Fix: Set the path to any endpoint your app responds to. / works for most web applications. You don’t need a dedicated /health endpoint.

Step 4: Check if the app needs more startup time

Some applications (especially Java/JVM, large Python/Django, or apps that run database migrations on startup) take longer than the default health check window.

Default window: 30s grace + (3 retries × 10s interval) = ~60 seconds total.

If your app needs more time:

1. Increase the startup grace period (e.g., 60 seconds instead of 30).
2. Increase the retry count (e.g., 6 instead of 3).
3. Or both.

Step 5: Check for missing environment variables

Applications often crash silently or hang when a required environment variable is missing. Common culprits:

• DATABASE_URL — App tries to connect to a database, hangs on connection timeout.
• SECRET_KEY — Framework refuses to start without it.
• API_KEY — App starts but throws an error on the first request.

Fix: Review the service’s Environment tab. Check your application’s documentation for required variables.

Step 6: Test locally

Build and run the container locally to confirm it starts and responds:

docker build -t myapp .
docker run -p 3000:3000 -e DATABASE_URL=... myapp
curl http://localhost:3000/health

If it works locally but fails on Clank, the issue is likely an environment variable, port configuration, or resource limit difference.

Quick reference

Symptom	Likely cause	Fix
”Connection refused” in logs	Wrong port configured	Match port to app’s listen port
No logs at all	Container crashing on start	Check for missing env vars or entrypoint errors
Logs show app started	Wrong health check path	Set path to / or a valid endpoint
Works locally, fails on Clank	Missing env var or resource limit	Compare env vars and resource settings
Intermittent failures	App starts slowly	Increase startup grace and retries

Next steps

• Health Checks concept — How health checks work and their configuration options.
• Deployment Failures — Other types of deployment failures.