highFoundationSymptom-first#containers#entrypoint#exit-code#restart

Container exits immediately after start — exit code nonzero

docker ps shows container Exited (1) seconds ago

Likely source:availabilityconfiguration

Focused incident mode — strips away everything but this runbook.

Symptoms

  • docker ps shows container Exited (1) seconds ago
  • Container starts then disappears from docker ps -a with non-zero exit code
  • docker logs <CONTAINER> shows a brief error then process terminates

Exit code 0 with a stopped container almost always means the process daemonized or had no long-running foreground task. Use --rm to auto-cleanup test containers during debugging.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Container exit status

    docker inspect <CONTAINER> --format='{{.State.ExitCode}}'

  • Last container logs

    docker logs <CONTAINER>

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • Exit code 127 (command not found)
  • docker logs shows 'exec format error' or 'not found'
  • Image was rebuilt without the expected binary

Confirm before fixing

docker inspect <IMAGE> --format='{{.Config.Entrypoint}} {{.Config.Cmd}}'
READ

Read the image's entrypoint and cmd

Fix

docker run --entrypoint /bin/bash <IMAGE> -c 'ls /usr/local/bin/'
CHANGE

Override entrypoint to inspect the filesystem

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
docker inspect <CONTAINER> --format='{{.State.ExitCode}}'
READ

Identify the exit code class

2
docker logs <CONTAINER>
READ

Read the crash output

3
docker inspect <IMAGE> --format='Entrypoint: {{.Config.Entrypoint}} CMD: {{.Config.Cmd}}'
READ

Verify the image's entrypoint and cmd

4
docker run --rm --entrypoint /bin/sh <IMAGE> -c 'ls / && echo OK'
CHANGE

Probe the image filesystem if entrypoint is suspect

Prevention

  • Always use the exec form of ENTRYPOINT and CMD (JSON array, not shell string).
  • Run the process in the foreground (no forking) — use exec or --foreground flags.
  • Test the image locally with docker run --rm before deploying to production.
  • Include a HEALTHCHECK instruction to catch silent startup failures early.

Related runbooks

Same stack, same failure family — worth a skim.

OOMKilled container — memory limit exceededcritical

docker ps shows container Exited (137) or Exited (139)

DockerFoundationUSE3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.