How to fix Container did not respond to SIGTERM within timeout in Docker

DockerINTERMEDIATEMEDIUM

This error occurs when Docker sends a SIGTERM signal to gracefully stop a container, but the process inside doesn't respond before the timeout expires. Docker then forcibly kills the container with SIGKILL. The fix involves proper signal handling, using exec form in Dockerfiles, or adding an init process.

What this error means

When you run `docker stop`, Docker sends a SIGTERM signal to the main process (PID 1) inside the container, giving it a chance to gracefully shut down. If the process doesn't exit within the timeout period (default: 10 seconds), Docker sends SIGKILL to forcibly terminate the container. The "Container did not respond to SIGTERM within timeout" error indicates that your application didn't handle the SIGTERM signal properly. This is a common issue because PID 1 processes in containers have special behavior: they won't receive signals unless they explicitly install signal handlers for them. This problem often occurs when: 1. Your application runs via a shell wrapper (e.g., `CMD /app/start.sh`) where the shell intercepts signals 2. Your process manager or runtime doesn't forward signals to child processes 3. Your application doesn't implement SIGTERM handlers 4. The application's graceful shutdown takes longer than the configured timeout

How to fix "Container did not respond to SIGTERM within timeout"

1Use exec form for CMD and ENTRYPOINT

The most common cause is using shell form in your Dockerfile, which wraps your command in /bin/sh -c. The shell doesn't forward signals to child processes.

Instead of shell form:

dockerfile

# BAD - shell form, wraps in /bin/sh -c
CMD /app/server
ENTRYPOINT /docker-entrypoint.sh

Use exec form (JSON array):

dockerfile

# GOOD - exec form, process runs directly as PID 1
CMD ["/app/server"]
ENTRYPOINT ["/docker-entrypoint.sh"]

Verify your process is PID 1:

bash

docker exec <container> ps aux

Your main application should be PID 1, not /bin/sh.

2Use exec in shell entrypoint scripts

If you need a shell script as entrypoint (for environment setup, etc.), use exec to replace the shell with your application:

bash

#!/bin/bash
# docker-entrypoint.sh

# Do setup work
echo "Setting up environment..."
export DATABASE_URL="postgres://..."

# IMPORTANT: Use exec to replace shell with main process
# This ensures your app receives signals directly
exec node /app/server.js

Without exec, the shell remains as PID 1 and your app runs as a child process. When Docker sends SIGTERM to PID 1 (the shell), it's not forwarded to your application.

Before (shell remains PID 1):

bash

PID 1: /bin/bash /docker-entrypoint.sh
PID 8: node /app/server.js  <- doesn't receive SIGTERM

After exec (app is PID 1):

bash

PID 1: node /app/server.js  <- receives SIGTERM directly

3Add an init process with --init or tini

Use Docker's built-in init process to properly handle signals and reap zombie processes:

Using Docker's --init flag:

bash

docker run --init myimage

In Docker Compose:

yaml

services:
  myapp:
    image: myimage
    init: true

Or install tini in your Dockerfile:

dockerfile

# For Alpine
RUN apk add --no-cache tini
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["/app/server"]

# For Debian/Ubuntu
RUN apt-get update && apt-get install -y tini
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["/app/server"]

Tini runs as PID 1 and:
- Forwards signals to your application
- Reaps zombie processes
- Handles the special PID 1 signal semantics

4Implement SIGTERM handlers in your application

If your application runs as PID 1, it must explicitly handle SIGTERM:

Node.js:

javascript

process.on('SIGTERM', () => {
  console.log('Received SIGTERM, shutting down gracefully...');
  server.close(() => {
    console.log('Server closed');
    process.exit(0);
  });

  // Force exit after timeout if graceful shutdown fails
  setTimeout(() => {
    console.error('Graceful shutdown timed out, forcing exit');
    process.exit(1);
  }, 8000);
});

Python:

python

import signal
import sys

def handle_sigterm(signum, frame):
    print('Received SIGTERM, shutting down...')
    # Cleanup code here
    sys.exit(0)

signal.signal(signal.SIGTERM, handle_sigterm)

Go:

sigs := make(chan os.Signal, 1)
signal.Notify(sigs, syscall.SIGTERM, syscall.SIGINT)

go func() {
    <-sigs
    log.Println("Received shutdown signal")
    // Cleanup and shutdown
    os.Exit(0)
}()

Java:

java

Runtime.getRuntime().addShutdownHook(new Thread(() -> {
    System.out.println("Shutting down gracefully...");
    // Cleanup code
}));

5Increase the stop timeout

If your application legitimately needs more time to shut down gracefully, increase the timeout:

docker stop command:

bash

docker stop --time=30 <container>  # Wait 30 seconds
docker stop -t 60 <container>       # Wait 60 seconds
docker stop -t -1 <container>       # Wait indefinitely

Docker Compose:

yaml

services:
  myapp:
    image: myimage
    stop_grace_period: 30s

Kubernetes:

yaml

spec:
  terminationGracePeriodSeconds: 30

Note: This should be a last resort. If your app needs more than 10 seconds to shut down, consider:
- Pre-draining connections before stop
- Reducing cleanup work
- Running cleanup as a separate process

6Fix signal handling in shell scripts

If you must use a shell script that doesn't exec, add proper signal trapping:

bash

#!/bin/bash

cleanup() {
    echo "Caught signal, cleaning up..."
    kill -TERM "$child_pid" 2>/dev/null
    wait "$child_pid"
    exit 0
}

trap cleanup SIGTERM SIGINT

# Run your app in background
/app/server &
child_pid=$!

# Wait for it (this allows trap to work)
wait "$child_pid"

Important: Using sleep or tail -f blocks signal processing. Always use wait to allow traps to execute:

bash

# BAD - blocks signals
/app/server &
tail -f /dev/null

# GOOD - allows signal handling
/app/server &
wait $!

7Configure the correct stop signal

Some applications expect a different signal than SIGTERM. For example, nginx and PHP-FPM use SIGQUIT for graceful shutdown.

In Dockerfile:

dockerfile

FROM nginx:alpine
STOPSIGNAL SIGQUIT

When running container:

bash

docker run --stop-signal=SIGQUIT nginx

In Docker Compose:

yaml

services:
  nginx:
    image: nginx
    stop_signal: SIGQUIT

Common stop signals by application:
- nginx: SIGQUIT
- PHP-FPM: SIGQUIT
- Apache: SIGWINCH (graceful) or SIGTERM
- Most applications: SIGTERM (default)

How to fix Container did not respond to SIGTERM within timeout in Docker

What this error means

Typical symptoms

Common causes

How to fix "Container did not respond to SIGTERM within timeout"

Advanced notes

Related errors

Official resources & further reading