How to fix FailedPreStopHook in Kubernetes

KubernetesINTERMEDIATELOW

PreStopHookError occurs when a preStop lifecycle hook fails during pod termination. The hook failure is logged but termination continues. Ensure hooks complete within the grace period.

What this error means

PreStopHookError (FailedPreStopHook) occurs when a container's preStop lifecycle hook fails during pod termination. Unlike postStart hooks, preStop hook failures don't prevent termination—the pod continues shutting down regardless. PreStop hooks run synchronously before SIGTERM is sent to the container. They're used for graceful shutdown tasks like draining connections, deregistering from service discovery, or completing in-flight requests. Failures are logged as warnings but don't block termination.

Typical symptoms

How to fix "FailedPreStopHook"

1Check termination events

View events during pod deletion:

bash

kubectl describe pod <pod-name>
kubectl get events --field-selector involvedObject.name=<pod-name>

Look for:
- FailedPreStopHook warnings
- Killing container with grace period messages
- Time between termination start and completion

2Verify hook completes within grace period

The preStop hook must finish within terminationGracePeriodSeconds:

yaml

spec:
  terminationGracePeriodSeconds: 60  # Total time for hook + shutdown
  containers:
  - name: app
    lifecycle:
      preStop:
        exec:
          command: ["/scripts/graceful-shutdown.sh"]  # Must complete in < 60s

If your hook takes 30 seconds and container needs 10 seconds to stop, set grace period to at least 45 seconds.

3Test hook execution manually

Test the hook in a running container:

bash

kubectl exec -it <pod-name> -- /bin/sh

# Run the hook command
/scripts/graceful-shutdown.sh
echo $?  # Should be 0
time /scripts/graceful-shutdown.sh  # Check duration

Ensure the script exists, is executable, and completes quickly.

4Fix YAML syntax issues

Common configuration mistakes:

yaml

# Wrong - extra quotes
command: ['"/bin/sh"', '-c', 'sleep 10']

# Correct
command: ["/bin/sh", "-c", "sleep 10"]

# Wrong - missing array brackets
command: /bin/sh -c "sleep 10"

# Correct
command: ["/bin/sh", "-c", "sleep 10"]

Validate YAML syntax before applying.

5Redirect output for debugging

PreStop output isn't captured by kubectl logs. Redirect to PID 1:

yaml

lifecycle:
  preStop:
    exec:
      command:
      - /bin/sh
      - -c
      - |
        echo "Starting graceful shutdown" > /proc/1/fd/1
        /scripts/shutdown.sh > /proc/1/fd/1 2>&1
        echo "Shutdown complete" > /proc/1/fd/1

This helps debug what the hook is doing during termination.

6Consider alternatives to preStop hooks

If preStop is problematic, consider these alternatives:

Handle SIGTERM in application:

python

import signal
def shutdown(signum, frame):
    drain_connections()
    sys.exit(0)
signal.signal(signal.SIGTERM, shutdown)

Use a sidecar for cleanup:
Sidecars can handle deregistration independently.

Increase grace period:
Give more time if shutdown genuinely needs it.

How to fix FailedPreStopHook in Kubernetes

What this error means

Typical symptoms

Common causes

How to fix "FailedPreStopHook"

Advanced notes

Related errors

Official resources & further reading