Docker container exits immediately: how to diagnose it

A container that exits immediately prints its ID during docker run, appears briefly in docker ps, then vanishes. docker ps -a lists it as Exited with an uptime measured in seconds. Unlike a restart loop, it stays stopped.

A Docker container is a Linux process wrapper, not a virtual machine. Its lifecycle is bound to PID 1 in the container’s namespace. When that process completes, crashes, or is killed, the container exits. An immediate exit means the process finished its work, failed to start, or was terminated during initialization. This guide gives you a diagnostic flow to find out why PID 1 terminated, interpret the exit code, and fix the root cause.

Common causes

CauseWhat it looks likeFirst thing to check
Foreground process completed normallyExit code 0; container ran its command and finisheddocker logs and the command/entrypoint in the image
Command or binary not foundExit code 127; shell cannot find the executabledocker inspect --format='{{.Config.Cmd}} {{.Config.Entrypoint}}'
Permission denied on executableExit code 126; file exists but cannot executeFile permissions inside the image or mount
Application crash on startupExit code 1; stderr shows a stack trace or config errordocker logs --tail 100
OOM kill during initializationExit code 137; logs may be empty or truncateddocker inspect --format='{{.State.OOMKilled}}'
Daemonized process inside containerExit code 0; app forks to background and main shell exitsWhether the app is running in foreground mode
Shell-form ENTRYPOINT or CMDShell exits when the command fails; app does not run as PID 1docker inspect for exec vs shell form
Missing environment or secretsExit code 1; application logs mention missing variablesdocker inspect --format='{{.Config.Env}}'

Quick checks

# Quick checks for an immediately exited container
docker ps -a --filter name=<container_name> --format "table {{.Names}}\t{{.Status}}\t{{.RunningFor}}"
docker inspect --format '{{.State.ExitCode}}' <container_name>
docker inspect --format '{{.State.OOMKilled}}' <container_name>
docker logs --tail 100 <container_name>
docker inspect --format 'Cmd={{.Config.Cmd}} Entrypoint={{.Config.Entrypoint}}' <container_name>
docker run --rm -it --entrypoint sh <image>
sudo dmesg | grep -i "oom"
sudo journalctl -u docker.service -p err --since "10 minutes ago"

How to diagnose it

  1. Check the exit code. Run docker inspect --format '{{.State.ExitCode}}' <name>. Code 0 means the process completed successfully. Code 1 means a general application error. Code 126 means a permission problem. Code 127 means a missing binary. Codes 128+N mean the process was killed by signal N (137 for SIGKILL, 139 for SIGSEGV, 143 for SIGTERM). The exit code tells you whether to look at application logic, configuration, or the kernel.

  2. Cross-reference with OOMKilled. Run docker inspect --format '{{.State.OOMKilled}}' <name>. If this is true and the exit code is 137, the kernel OOM killer terminated the container because it exceeded its memory limit. Run sudo dmesg | grep -i oom for confirmation. If OOMKilled is false and the exit code is 137, something else sent SIGKILL.

  3. Read the logs. Run docker logs --tail 100 <name>. If the application crashed before flushing output or writes only to a file inside the container, the logs may be empty. For Python applications, missing PYTHONUNBUFFERED=1 often hides startup errors because stdout is buffered by default. If logs are empty, run the container interactively with --entrypoint sh and execute the command manually to see the error.

  4. Inspect the image command. Run docker inspect on the container or image and check Config.Cmd and Config.Entrypoint. A shell-form command such as CMD node server.js wraps the process in /bin/sh -c, making /bin/sh PID 1. If the shell finishes or the process daemonizes, the container exits. An exec-form command such as CMD ["node", "server.js"] runs the binary directly as PID 1.

  5. Verify foreground mode. If the application is a server that daemonizes by default (for example, NGINX, Apache, or gunicorn with -D), the main process forks to background and the initial process exits. The container dies immediately because PID 1 finished. Check the application flags and ensure it runs in the foreground (for example, nginx -g 'daemon off;' or gunicorn --foreground).

  6. Check for missing dependencies. Exit code 127 or errors in logs about missing files often mean the container filesystem lacks a binary, library, or mounted configuration file. Run an interactive shell in the image and verify paths and permissions.

  7. Review resource limits. If the container is created but dies instantly with exit code 137 and OOMKilled is true, review the memory limit. Even if the application normally fits, initialization spikes (JVM heap allocation, large imports) can exceed the limit immediately. Temporarily raise the limit to test. Do not remove limits entirely on production hosts if the application behavior is unknown.

Metrics and signals to monitor

SignalWhy it mattersWarning sign
Container exit codeClassifies the failure mechanismAny non-zero code for a long-running service
OOMKilled statusDistinguishes OOM from external SIGKILLtrue with exit code 137
Container restart countReveals crash loops masked by restart policiesNon-zero restart count after a fresh start
Container start-to-exit durationDistinguishes instant failure from slow crashStartedAt and FinishedAt in docker inspect are seconds apart
Docker daemon errorsCatches runtime or storage driver issuesErrors in journalctl -u docker.service
Host memory pressureSystem-wide OOM can kill containers without individual limitsdmesg OOM messages or high memory usage
Container CPU throttlingCan cause startup timeouts that trigger killsnr_throttled increasing in cgroup cpu.stat

Fixes

If the cause is a missing or misconfigured command

Use docker inspect <image> to confirm Cmd and Entrypoint, then verify the binary exists inside the image with an interactive shell. If using shell form, switch to exec form so the binary receives Unix signals directly and runs as PID 1. Verify that volume mounts or secrets required at startup are present.

If the cause is a daemonizing process

Reconfigure the application to stay in the foreground. Examples include nginx -g 'daemon off;', apachectl -D FOREGROUND, or removing -D from gunicorn. The process running as PID 1 must not fork to background and exit. If you cannot change the application, use a lightweight init system such as tini, but ensure the final process remains in the foreground.

If the cause is an OOM kill

Increase the container memory limit or reduce the application’s memory footprint. For JVM workloads, ensure -Xmx leaves headroom for metaspace, thread stacks, and native memory. A common practice is setting -Xmx to roughly 75% of the container limit. Check dmesg to confirm the OOM killer targeted your container’s cgroup.

If the cause is an application crash

Fix the underlying code or configuration. Use docker run --rm -it --entrypoint sh <image> to reproduce the startup sequence manually. Check environment variables, secrets mounts, and network dependencies. If the application writes logs to a file inside the container, read that file directly or redirect output to stdout/stderr.

If the cause is empty or buffered logs

Set unbuffered output for interpreted languages. For example, set ENV PYTHONUNBUFFERED=1 in the Dockerfile. Redirect application logs to stdout/stderr instead of filesystem paths inside the container so docker logs captures startup errors.

Prevention

  • Use exec form for ENTRYPOINT and CMD. This avoids /bin/sh wrapper issues and ensures the application receives SIGTERM correctly.
  • Run applications in the foreground. Verify that your PID 1 process does not daemonize. Document required flags in your Dockerfile or orchestration manifests.
  • Set log output to stdout/stderr and configure unbuffered modes. Do not rely on filesystem logs inside the container for startup errors.
  • Configure health checks for long-running containers. Health checks catch runtime dependency failures and hangs that might eventually trigger a restart loop.
  • Set appropriate resource limits. Size memory limits to account for startup spikes, not just steady-state usage.
  • Validate images in CI. Run the container in your build pipeline and check that it stays running for a minimum duration before pushing the image to a registry.
  • Monitor exit codes and OOMKilled status proactively. Do not wait for disk exhaustion from log-filled crash loops.

How Netdata helps

Netdata monitors container state changes and cgroup metrics in real time. Instead of manually polling docker inspect, correlate the exit with resource pressure or daemon events using:

  • Container state charts show when a container moves to exited and track abnormal termination counts.
  • Memory utilization vs. limit identifies OOM risk before the kernel kills the container.
  • Docker daemon metrics expose engine runtime errors and response latency that can prevent a container from starting.
  • CPU throttling metrics reveal whether CFS bandwidth limits slow startup enough to trigger health-check kills or timeouts.