Skip to main content
RunBook Academy

← All runbooks in Docker & Containers

medium riskservice affecting~15 min

Runbook: Application container exits immediately after start

1 · Prerequisites

Confirm every item is in place before any state change.

  • docker exec available
  • Container logs accessible

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

  • · docker ps -a | grep CONTAINER
  • · docker inspect CONTAINER --format "{{.State.ExitCode}}"

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

  1. 1Check the exit code (0=clean, 1=app error, 126=cant exec, 127=not found, 137=SIGKILL, 143=SIGTERM)
  2. 2Read the logs with docker logs CONTAINER --tail 100
  3. 3Inspect the image with docker run --rm --entrypoint /bin/sh myorg/myapp:1.0.0
  4. 4Verify resource limits are not exceeded

4 · Verification

Confirm the procedure actually fixed the problem.

  • ✓Container stays running under normal load
  • ✓docker ps shows Up X minutes
  • ✓The application responds on its endpoints

5 · Rollback

If verification fails, undo the procedure in reverse order.

  • ↶Re-deploy the previous image version
  • ↶Restore from volume backup if state was lost
  • ↶Page the on-call engineer for the service

6 · Escalation

When the runbook isn't enough, contact:

  • · Page the on-call engineer if diagnosis takes more than 15 minutes
  • · Capture full logs and inspect output before changing anything

Symptoms

  • docker ps shows the container in Exited (1) state.
  • docker logs CONTAINER shows an error message.
  • Health check (if configured) reports unhealthy.
  • The container keeps restarting if restart: always is set.

Diagnosis

  1. Check the exit code.
  2. docker ps -a | grep CONTAINER
  3. docker inspect CONTAINER --format "{{.State.ExitCode}}"
  4. Common exit codes: 0 (clean exit), 1 (app error), 126 (can't execute), 127 (not found), 137 (SIGKILL), 143 (SIGTERM).
  5. Read the logs.
  6. docker logs CONTAINER --tail 100
  7. Look for stack traces, missing dependencies, configuration errors.
  8. Check the entrypoint.
  9. docker inspect CONTAINER --format "{{.Config.Entrypoint}} {{.Config.Cmd}}"
  10. Confirm the entrypoint exists in the image and is executable.
  11. Inspect the image.
  12. docker run --rm --entrypoint /bin/sh myorg/myapp:1.0.0
  13. Then inside the container:
  14. ls -la /app/ (or wherever the entrypoint expects)
  15. /app/entrypoint.sh --help (test the entrypoint manually)
  16. Check resource limits.
  17. docker inspect CONTAINER --format "{{.HostConfig.Memory}}"
  18. OOM-killed containers exit with 137. Increase the limit if needed.

Resolution

Based on the diagnosis:

  • Application error (exit 1). Fix the application bug. Re-deploy.
  • Missing binary (exit 126/127). The image is broken; rebuild it.
  • OOM killed (exit 137). Increase memory limit or fix the leak.
  • Killed by SIGTERM (exit 143). Usually a startup-timeout exceeded.

Verification

  1. The container starts and stays running. docker ps shows Up X minutes.
  2. The healthcheck passes. docker inspect shows Status: healthy.
  3. The application responds. docker exec CONTAINER curl localhost:8080/health returns 200.

Escalation

If the container still fails after these steps:

  • Capture the full log output.
  • Capture the exit code and any OOMKilled flag.
  • Page the on-call engineer for the affected service.
  • Do not restart the container repeatedly; that wastes evidence.

Prevention

  • Add a healthcheck that exercises the application’s actual functionality, not just curl /.
  • Set sensible restart: on-failure:5 to limit crash loops.
  • Capture the entrypoint’s exit code in a wrapper script that logs to stderr before exiting.

References

  1. docker ps documentation
  2. docker logs documentation