Container exits immediately or keeps restarting

A container that stops right after docker run, or loops in "Restarting", almost always has a main process that exits or crashes. The exit code tells you why.

#docker #debug #troubleshooting

Diagnose

Find out why it stopped

SHELL

1docker ps -a # STATUS shows Exited (code)

2docker logs --tail 50 <container> # the app's last words

3docker inspect -f '{{.State.ExitCode}} OOM={{.State.OOMKilled}}' <container>

5# Get a shell in the same image, bypassing the failing command

6docker run --rm -it --entrypoint sh <image>

Exit codes

Code	Meaning	Usual cause
`0`	Finished successfully	Main process is not long-running (a script, or a service started in the background)
`1`	Application error	Bad config, missing env var, cannot reach DB: read the logs
`126`	Command not executable	Missing execute permission on the entrypoint script
`127`	Command not found	Typo in CMD, or binary missing from a slim image
`137`	Killed (SIGKILL)	Out of memory (`OOMKilled: true`) or `docker kill`
`139`	Segmentation fault	Native crash, often wrong CPU architecture
`143`	Terminated (SIGTERM)	Normal `docker stop`

Common fixes

Exited (0) immediately: the process must stay in the foreground, e.g. nginx -g "daemon off;", not a service that forks and returns. For a test container use sleep infinity
Missing config: add the required -e variables or --env-file
Dependency not ready: the app starts before the DB accepts connections; add retries or a Compose healthcheck with condition: service_healthy
Windows line endings in entrypoint.sh give no such file or directory: convert with dos2unix
OOM (137): raise --memory, or tune the app heap (e.g. -XX:MaxRAMPercentage=75 for Java)

Tip

A restart policy hides crashes by restarting forever. While debugging, run without --restart (or restart: "no" in Compose) so the failure stays visible.

Docker/Troubleshooting/Container exits immediately or keeps restarting

TroubleUpdated 3 weeks ago

Container exits immediately or keeps restarting

A container that stops right after docker run, or loops in "Restarting", almost always has a main process that exits or crashes. The exit code tells you why.

#docker #debug #troubleshooting

Diagnose

Find out why it stopped

SHELL

1docker ps -a # STATUS shows Exited (code)

2docker logs --tail 50 <container> # the app's last words

3docker inspect -f '{{.State.ExitCode}} OOM={{.State.OOMKilled}}' <container>

5# Get a shell in the same image, bypassing the failing command

6docker run --rm -it --entrypoint sh <image>

Exit codes

Code	Meaning	Usual cause
`0`	Finished successfully	Main process is not long-running (a script, or a service started in the background)
`1`	Application error	Bad config, missing env var, cannot reach DB: read the logs
`126`	Command not executable	Missing execute permission on the entrypoint script
`127`	Command not found	Typo in CMD, or binary missing from a slim image
`137`	Killed (SIGKILL)	Out of memory (`OOMKilled: true`) or `docker kill`
`139`	Segmentation fault	Native crash, often wrong CPU architecture
`143`	Terminated (SIGTERM)	Normal `docker stop`

Common fixes

Exited (0) immediately: the process must stay in the foreground, e.g. nginx -g "daemon off;", not a service that forks and returns. For a test container use sleep infinity
Missing config: add the required -e variables or --env-file
Dependency not ready: the app starts before the DB accepts connections; add retries or a Compose healthcheck with condition: service_healthy
Windows line endings in entrypoint.sh give no such file or directory: convert with dos2unix
OOM (137): raise --memory, or tune the app heap (e.g. -XX:MaxRAMPercentage=75 for Java)

Tip

A restart policy hides crashes by restarting forever. While debugging, run without --restart (or restart: "no" in Compose) so the failure stays visible.