How to fix FailedPreStopHook in Kubernetes

KubernetesINTERMEDIATELOWUpdated Oct 1, 2026· 188 views

The FailedPreStopHook warning occurs when a container's preStop lifecycle hook fails during pod termination. Unlike postStart failures, this doesn't prevent termination—the pod will still be killed.

Quick fix

Fixes FailedPreStopHook

kubectl describe pod <pod-name>
  1. Check pod events for hook failure
  2. Verify YAML command syntax
  3. Increase termination grace period
  4. Capture preStop output for debugging
kubernetes — error
kubectl describe pod <pod-name>
FailedPreStopHook

What this error means

The FailedPreStopHook warning appears when a pod's preStop lifecycle hook fails to execute successfully during termination. PreStop hooks are designed to perform graceful shutdown tasks like draining connections, flushing logs, or deregistering from service discovery. Important: A preStop hook failure does NOT prevent pod termination. The pod will still be killed after the terminationGracePeriodSeconds expires. The warning is informational—it tells you your graceful shutdown logic didn't work as intended. PreStop hooks execute synchronously—Kubernetes waits for the hook to complete before sending SIGTERM to the container. If the hook takes too long, the entire grace period may be consumed, leaving no time for the application's own shutdown handling.

Typical symptoms

  • FailedPreStopHook warning in pod events during termination
  • Pod terminates without completing graceful shutdown tasks
  • Connections dropped abruptly during deployments
  • Service discovery still routing to terminated pods
  • Pod stuck in Terminating state until grace period expires

Common causes

  1. PreStop command exits with non-zero exit code
  2. Hook takes longer than terminationGracePeriodSeconds
  3. Command syntax errors in YAML (quoting, escaping issues)
  4. HTTP hook using wrong protocol (HTTP vs HTTPS)
  5. Container exits before preStop hook completes

How to fix "FailedPreStopHook"

1Check pod events for hook failure

View termination events to see preStop failures:

bash
kubectl describe pod <pod-name>

Look for:

bash
Warning  FailedPreStopHook  Exec lifecycle hook failed
2Verify YAML command syntax

Common syntax errors cause silent failures. Ensure proper array format:

yaml
# Correct
lifecycle:
  preStop:
    exec:
      command: ["/bin/sh", "-c", "nginx -s quit"]

# Wrong - extra quotes
lifecycle:
  preStop:
    exec:
      command: ["/bin/sh", "-c", "'nginx -s quit'"]
3Increase termination grace period

Ensure the grace period exceeds preStop duration plus shutdown time:

yaml
spec:
  terminationGracePeriodSeconds: 60  # Default is 30
  containers:
  - name: app
    lifecycle:
      preStop:
        exec:
          command: ["/bin/sh", "-c", "sleep 10 && /shutdown.sh"]
4Capture preStop output for debugging

PreStop output doesn't appear in kubectl logs. Redirect to container stdout:

yaml
lifecycle:
  preStop:
    exec:
      command:
      - /bin/sh
      - -c
      - |
        echo "Starting graceful shutdown" >> /proc/1/fd/1
        /shutdown.sh 2>&1 >> /proc/1/fd/1
5Test hook by manually deleting pod

Trigger termination to test your preStop hook:

bash
# Delete pod and watch events
kubectl delete pod <pod-name> &
kubectl get events -w --field-selector involvedObject.name=<pod-name>

Note: PreStop hooks only run on forced termination, not when a container exits successfully on its own.

Advanced notes

PreStop hooks and SIGTERM handling have a race condition. The timeline is:
1. PreStop hook starts
2. Hook completes (or times out)
3. SIGTERM sent to container
4. App handles SIGTERM
5. SIGKILL at grace period end

If your hook runs for 25 seconds and grace period is 30 seconds, your app only has 5 seconds to handle SIGTERM before SIGKILL.

For load balancer scenarios, add a sleep in preStop to allow the load balancer to deregister the pod:

yaml
preStop:
  exec:
    command: ["/bin/sh", "-c", "sleep 15"]

This gives the load balancer time to stop sending traffic before the application starts shutting down.

Frequently asked questions

What does "FailedPreStopHook" mean?
The FailedPreStopHook warning appears when a pod's preStop lifecycle hook fails to execute successfully during termination. PreStop hooks are designed to perform graceful shutdown tasks like draining connections, flushing logs, or deregistering from service discovery. Important: A preStop hook failure does NOT prevent pod termination.
How do I fix "FailedPreStopHook"?
The FailedPreStopHook warning occurs when a container's preStop lifecycle hook fails during pod termination. Unlike postStart failures, this doesn't prevent termination—the pod will still be killed.
What causes "FailedPreStopHook"?
PreStop command exits with non-zero exit code Hook takes longer than terminationGracePeriodSeconds Command syntax errors in YAML (quoting, escaping issues)
Is the "FailedPreStopHook" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading