Articles

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.

Chisato Chisato · · 5 min read
Stacked cargo shipping containers at a port

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:

  1. You run docker stop (or Kubernetes deletes a pod).
  2. The runtime sends SIGTERM to PID 1.
  3. Your app never registered a SIGTERM handler, so nothing happens.
  4. The runtime waits out the grace period — 10 seconds by default for docker stop, 30 seconds by default for a Kubernetes pod — and then sends SIGKILL.
  5. SIGKILL cannot 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.

ApproachFixes signalsFixes zombiesNotes
Use exec form CMD/ENTRYPOINTPartlyNoNecessary baseline; app must still handle SIGTERM
exec at the end of entrypoint scriptsPartlyNoLets the app become PID 1
Handle SIGTERM in the appYesNoRequired for draining connections anyway
Run a minimal init (--init, tini, dumb-init)YesYesInit 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.

Chisato 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.

#Cloud #DevOps #Containers