Docs / Troubleshooting / App Unhealthy Restart Loop Playbook

App Unhealthy Restart Loop Playbook

Published · Last updated: May 2026 · 3 min read

Who this is for

Users whose Docker container app or Compose app shows a status of failed, is stuck in a restart loop, or passes the health check intermittently.

Step 1 — Read the App Logs

App logs are the first diagnostic tool:

  1. Open App detail → Logs tab.
  2. Read the most recent output.

Look for:

  • Application startup errors (crash on boot, missing env vars, DB connection failed)
  • OOM (Out of Memory) — container killed by kernel: killed, OOM, exit code 137
  • Port binding errors — EADDRINUSE, address already in use, bind: address already in use
  • Missing environment variables — undefined, env: ...not found

Step 2 — Check the Health Check Configuration

If the app passes the health check on startup but then fails:

  1. Open App detail → Settings (or edit the app).
  2. Review the Health check settings:
  • Path — the HTTP path the health check hits (e.g., /health)
  • Port — the port the health check uses
  1. Test the health check manually:
   curl http://<server-ip>:<port>/health

If the health check path does not exist in your app, the container will always appear unhealthy. Either:

  • Add a /health endpoint to your app.
  • Update the health check path to one that exists.
  • Disable the health check if your app does not support one.

See KB-04-13: Healthcheck Behavior.

Step 3 — Diagnose the Restart Loop

A restart loop means the container is crashing on startup and Docker is restarting it (based on restartPolicy).

Most common causes:

CauseLog signalFix
Missing environment variableCannot read property ... of undefined or env: VAR not foundAdd missing env var — see KB-04-08
Database not reachableECONNREFUSED, Connection refusedCheck DB host/port; check DB is running
Port already in useEADDRINUSE, bind: address already in useSee KB-12-15: Port Conflict Playbook
App crashes on startupStack trace ending with process exited with code 1Fix the application error shown in the trace
Out of memoryexit code 137, KilledIncrease server RAM or reduce app memory usage
Wrong image / bad tagNo such image: ..., manifest unknownPull the correct image; verify the tag exists

Step 4 — Stop the Restart Loop While You Fix

  1. Open App detail.
  2. Click Stop to halt the container.

This stops the restart loop and gives you time to fix the issue without resource exhaustion.

Step 5 — Fix and Redeploy

After fixing the root cause:

  1. Update env vars, image tag, or health check config.
  2. Click Deploy (or Start) to restart the app.
  3. Watch the Logs tab to confirm startup succeeds.

Related Articles