Docker exit code 143: SIGTERM and graceful shutdown failures

You are reviewing container exit codes after a deployment or node drain and see 143. If your monitoring alerts on it, you might think something failed. Exit code 143 is not an error. It is 128 plus signal 15 (SIGTERM), and it means the container’s PID 1 process received SIGTERM and exited voluntarily. This is exactly what docker stop is designed to do.

The operational problem is not the code itself, but what happens around it. If your application never receives the signal, it gets SIGKILL after the timeout and exits 137, potentially dropping connections and corrupting state. If your orchestrator pages you for 143 during a normal rolling restart, your alerts are noisy. If your stop timeout is too short for your database to finish checkpointing, you risk data inconsistency.

This guide explains how SIGTERM propagates through Docker, why it fails to reach your application, and how to fix the root cause so graceful shutdowns actually work.

What this means

Exit code 143 indicates that the container’s primary process terminated in response to SIGTERM. When you run docker stop, the daemon sends SIGTERM to the container’s PID 1, waits for a grace period (default 10 seconds), and then escalates to SIGKILL if the process is still running. A container that exits cleanly during that window reports 143.

Because Docker only signals PID 1, the identity of that process matters. If PID 1 is a shell launched by a shell-form CMD or ENTRYPOINT, the shell may not forward the signal to your application. The application keeps running until the grace period expires and SIGKILL arrives. In that case, the exit code becomes 137, not 143, and the shutdown is not graceful at all.

The same risk applies to wrapper scripts that spawn the application as a background subprocess instead of replacing themselves with exec. The signal stops at the shell, and the actual workload is blindsided.

Common causes

Quick checks

# Confirm exit code and OOM status
docker inspect --format '{{.State.ExitCode}} {{.State.OOMKilled}}' <container_id>

# Inspect entrypoint and command form
docker inspect --format '{{json .Config.Entrypoint}} {{json .Config.Cmd}}' <container_id>

# Check process tree inside the container
docker exec <container_id> ps -ef

# Send SIGTERM manually without a grace timer
# Warning: this stops the container immediately if the handler works
docker kill --signal=SIGTERM <container_id>

# Test whether a longer timeout prevents SIGKILL escalation
# Warning: this stops the container
docker stop --time=60 <container_id>

# Watch die and kill events to confirm timing
docker events --filter event=die --filter event=kill --since 1m

How to diagnose it

1. Verify the exit code and context. Use docker inspect to confirm the code is 143 and OOMKilled is false. If the code is 137, the process was killed, and the shutdown was not graceful. Check whether the stop was initiated by an operator, CI/CD pipeline, orchestrator, or node drain.
2. Inspect PID 1. Run docker exec <id> ps -ef or docker top <id> to identify the process at PID 1. If it is /bin/sh, bash, or another shell running your application as a child, the shell is likely blocking signal propagation.
3. Check the Dockerfile instruction form. Inspect Config.Entrypoint and Config.Cmd. If they appear as single strings rather than JSON arrays (for example, sh -c node server.js instead of ["node", "server.js"]), you are using shell form. Convert to JSON-array form or add exec to the wrapper script so the application replaces the shell.
4. Test signal delivery manually. Send docker kill --signal=SIGTERM <id> and watch the application logs. If the app begins its shutdown routine within seconds, its handler works and the signal is reaching it. If nothing happens until you send SIGKILL, the signal is blocked or the handler is missing.
5. Evaluate the stop timeout. If the app has a handler but needs more than 10 seconds to finish in-flight requests or flush state, docker stop will escalate to SIGKILL. Increase the timeout with docker stop --time=N, set stop_grace_period in Docker Compose, or adjust terminationGracePeriodSeconds in Kubernetes. Ensure the application’s handler has enough runway.
6. Check for child process and zombie leaks. If the application forks workers and PID 1 does not call waitpid(), zombies accumulate. During shutdown, unreaped children can hold open resources and delay exit. Use docker run --init to inject tini as PID 1, or add an init system like tini or dumb-init to the image.
7. Review orchestrator-side hooks and signals. In Kubernetes, the grace period clock starts when the pod is marked for deletion. The kubelet runs any configured preStop hook before sending SIGTERM to the container, so a preStop sleep for load-balancer deregistration consumes grace period budget before the container even receives the signal. If the combined time of the hook and the application’s shutdown exceeds terminationGracePeriodSeconds, the container is SIGKILL’d. Remove unnecessary sleep from preStop or increase the grace period to cover both the hook and the application shutdown.

flowchart TD
    A[Container exits 143] --> B{Was stop user-initiated?}
    B -->|Yes| C[Expected graceful shutdown]
    B -->|No| D[Check PID 1 process]
    D --> E{Shell or JSON array form?}
    E -->|Shell| F[Signal blocked by shell]
    E -->|JSON| G[App received SIGTERM?]
    G -->|No handler| H[Add SIGTERM handler]
    G -->|Handler exists| I[Check stop timeout]
    I --> J{Exceeds grace period?}
    J -->|Yes| K[Increase timeout or optimize shutdown]
    J -->|No| L[Check for zombie reaping issues]

Metrics and signals to monitor

Fixes

If shell form is blocking the signal

Convert CMD node server.js to CMD ["node", "server.js"] in the Dockerfile. If you must use a shell wrapper, use exec ./myapp so the application replaces the shell process and becomes PID 1.

If the application lacks a handler

Implement a SIGTERM handler in your application code. The handler should stop accepting new work, finish in-flight requests, flush buffers, and then exit. Test it by running the container locally and sending docker kill --signal=SIGTERM.

If the stop timeout is too short

Increase the timeout. For Docker CLI, use docker stop --time=N. For Docker Compose, set stop_grace_period. For Kubernetes, set terminationGracePeriodSeconds. Also align the application handler’s internal timeout to be shorter than the external limit.

If PID 1 does not reap zombies

Use docker run --init to inject Docker’s embedded tini-based init. This handles SIGTERM forwarding and zombie reaping without modifying the image. Alternatively, add tini or dumb-init to the image ENTRYPOINT.

If the orchestrator treats 143 as a failure

Update your alerting rules and runbooks. Exit code 143 is a successful graceful shutdown in response to SIGTERM. Whitelist it for stop, drain, and scale-down events. Alert on 137 (SIGKILL) or unexpected 143 outside of maintenance windows.

If preStop hooks consume the grace period

Remove artificial sleep from Kubernetes preStop hooks where possible. If you need delay for load-balancer drainage, increase terminationGracePeriodSeconds so the sum of hook duration and application shutdown fits comfortably inside the limit.

Prevention

• Use JSON-array form for all ENTRYPOINT and CMD instructions unless you specifically need shell expansion.
• Always use exec in wrapper scripts to replace the shell.
• Set STOPSIGNAL explicitly in the Dockerfile if your application uses a custom shutdown signal, so operators do not have to guess.
• Configure stop timeouts in deployment manifests, not just at runtime. Document how long your application needs to shut down cleanly.
• Test graceful shutdown in CI: start the container, send SIGTERM, assert that it exits 143 within the expected window and that no connections are dropped.
• Monitor for exit code 137 following stop events. That pattern means your graceful shutdown is broken even if the application eventually restarts.

How Netdata helps

• Correlate container exit code 143 spikes with deployment events or node drains to distinguish normal shutdowns from anomalies.
• Monitor container restart counts alongside exit codes to catch loops caused by signal propagation failures.
• Track application-level error rates and container lifecycle events on the same timeline to identify dropped connections during rolling updates.
• Visualize CPU and memory saturation to confirm the application had resources to complete its shutdown routine.

Related guides

• Docker commands hang: docker ps, inspect, and exec freezes
• Docker container exits immediately: how to diagnose it
• Docker container high CPU usage: causes and fixes
• Docker container high memory usage: how to diagnose it
• Docker container keeps restarting: causes, checks, and fixes
• Docker container memory leak: how to find one and prove it
• Docker container running but unhealthy: how to diagnose health check failures
• Docker CPU throttling: the hidden cause of container latency
• Docker daemon not responding: how to troubleshoot a hung dockerd
• Docker disk space full: how to troubleshoot /var/lib/docker
• Docker DNS not working inside containers
• Docker exit code 1: application errors and how to find them