The Docker PID 1 Problem: Signals and Zombie Processes
In a container, your app often runs as PID 1, which ignores default signals and must reap zombies. Why containers hang on stop and how to fix it.
The PID 1 problem is what happens when an application that was never designed to be an init system ends up running as process ID 1 inside a container. On Linux, PID 1 has two special responsibilities: the kernel does not apply default signal behavior to it, and it is expected to reap orphaned child processes. An ordinary app does neither. The symptoms are containers that take the full timeout to stop, shutdown code that never runs, and a slow buildup of zombie processes.
Why your app becomes PID 1
Containers use Linux PID namespaces to give each container its own process tree. The first process started in that namespace — whatever your image’s ENTRYPOINT or CMD launches — gets PID 1 inside it. On a normal Linux host, PID 1 is a real init system like systemd, which is built for the job. In a container, PID 1 is usually your Node.js server, Python worker, or Java service.
If you are new to how images and entry points fit together, Docker for beginners covers the basics.
Special rule one: default signal actions do not apply
Normally, if a process receives SIGTERM or SIGINT and has not installed a handler for it, the kernel applies the default action, which is to terminate the process. For PID 1, the kernel skips that default. A signal sent to PID 1 from within its namespace that has no registered handler is simply ignored.
This protects a real init system from being killed by accident, but in a container it means:
- You run
docker stop(or Kubernetes deletes a pod). - The runtime sends
SIGTERMto PID 1. - Your app never registered a
SIGTERMhandler, so nothing happens. - The runtime waits out the grace period — 10 seconds by default for
docker stop, 30 seconds by default for a Kubernetes pod — and then sendsSIGKILL. SIGKILLcannot be ignored, so the process dies abruptly, mid-request, with no cleanup.
Every deploy and scale-down now takes the maximum time, and in-flight work is dropped instead of drained. That defeats the purpose of graceful shutdown.
Some language runtimes install signal handlers by default, so behavior varies. The safe assumption is that unless your code explicitly handles SIGTERM, PID 1 will ignore it.
Special rule two: PID 1 must reap zombies
When a process exits, it does not disappear immediately. It becomes a zombie: an entry in the process table holding its exit status until its parent calls wait() to collect it. If the parent dies first, the orphan is re-parented to PID 1, which is expected to wait on it.
A real init system does this constantly. Your application almost certainly does not. If your app spawns child processes — shell commands, headless browsers, image converters — and any of those spawn grandchildren that outlive their parents, the orphans land on your app and are never reaped. Zombies use no CPU or memory beyond a process table slot, but a long-running container can accumulate enough of them to hit the PID limit and fail to start new processes.
The shell form trap
How you write CMD or ENTRYPOINT changes which process becomes PID 1.
# Shell form: PID 1 is /bin/sh, your app is its child
CMD node server.js
# Exec form: PID 1 is node itself
CMD ["node", "server.js"]
With the shell form, Docker runs your command through /bin/sh -c. The shell becomes PID 1 and your app becomes a child. Many minimal shells do not forward signals to children, so SIGTERM stops at the shell and your app never hears about it. The difference between CMD and ENTRYPOINT and their two forms is worth knowing in detail for exactly this reason.
The same issue appears with wrapper scripts. If entrypoint.sh does some setup and then runs node server.js as the last line, the script’s shell stays as PID 1. End the script with exec node server.js instead, which replaces the shell with your app so it inherits PID 1 directly.
How to fix it
There are four common approaches, and they combine well.
| Approach | Fixes signals | Fixes zombies | Notes |
|---|---|---|---|
Use exec form CMD/ENTRYPOINT | Partly | No | Necessary baseline; app must still handle SIGTERM |
exec at the end of entrypoint scripts | Partly | No | Lets the app become PID 1 |
Handle SIGTERM in the app | Yes | No | Required for draining connections anyway |
Run a minimal init (--init, tini, dumb-init) | Yes | Yes | Init forwards signals and reaps children |
Handle signals in your application. This is worth doing no matter what else you choose, because only your code knows how to stop accepting new work, finish in-flight requests, and close database connections cleanly.
Add a tiny init process. docker run --init injects a minimal init as PID 1, which launches your app as its child, forwards signals to it, and reaps any zombies. You can get the same effect inside the image by installing a small init such as tini or dumb-init and making it the ENTRYPOINT. These add almost no overhead and remove both halves of the problem.
Use the platform’s options. In Kubernetes, setting shareProcessNamespace: true on a pod makes the pod’s infrastructure container PID 1 for all containers in the pod, and it handles reaping. That changes process visibility between containers, so it is a deliberate choice rather than a default fix. Understanding how pods, deployments, and services relate helps when deciding where shutdown logic belongs.
How to check what you have
Run docker exec <container> ps -ef (or ps with whatever your image provides) and look at PID 1. If it is /bin/sh -c ..., you are using the shell form or a script without exec. Then time a docker stop: if it consistently takes the full grace period, PID 1 is ignoring SIGTERM. Finally, look for processes in state Z in a long-running container to spot unreaped zombies.
Minimal images built with multi-stage builds sometimes omit ps entirely; reading /proc/1/cmdline from inside the container gives the same answer.
The takeaway
Inside a container, whatever you launch first becomes PID 1, and Linux expects PID 1 to handle signals explicitly and reap orphaned children. Apps that do neither ignore SIGTERM, get killed after the timeout, and can leak zombies. Use the exec form, exec the final command in wrapper scripts, handle SIGTERM in your code, and add a minimal init like --init or tini when your container spawns child processes.
Tagged
Keep reading
The Lycoris Team · · 5 min read Dockerfile CMD vs ENTRYPOINT: Differences and When to Use
CMD sets a container's default command or arguments; ENTRYPOINT sets the fixed executable. How CMD and ENTRYPOINT interact, exec vs shell form, and PID 1.
Chisato · · 4 min read Virtual Machines vs Containers: Key Differences
VMs virtualize hardware with a full guest OS per instance; containers share the host kernel and isolate processes. What that trade-off costs and buys you.
Chisato · · 5 min read Docker Networking Modes: Bridge, Host, and Overlay
Docker's default bridge network isolates containers with NAT; host mode shares the host's network stack; overlay connects containers across hosts.