How to fix FailedPreStopHook in Kubernetes

KubernetesINTERMEDIATELOWUpdated Dec 6, 2025· 162 views

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.

Quick fix

Fixes FailedPreStopHook

kubectl describe pod <pod-name>
kubectl get events --field-selector involvedObject.name=<pod-name>
  1. Check termination events
  2. Verify hook completes within grace period
  3. Test hook execution manually
  4. Fix YAML syntax issues
kubernetes — error
kubectl describe pod <pod-name>
kubectl get events --field-selector involvedObject.name=<pod-name>
FailedPreStopHook

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

  • Events show FailedPreStopHook warning during pod deletion
  • Pod termination takes longer than expected
  • Pod killed forcefully after grace period expires
  • Graceful shutdown tasks not completing
  • Services receiving traffic to terminating pods
  • Connection errors during deployments

Common causes

  1. PreStop hook exceeds terminationGracePeriodSeconds
  2. Hook command has typos or syntax errors
  3. Hook script not executable or not found
  4. Hook tries to access resources no longer available
  5. Container exits before hook can run
  6. HTTPS scheme in hook causing connection errors
  7. Hook command exits with non-zero status

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.

Advanced notes

PreStop hook execution timeline:
1. Pod deletion requested
2. Pod removed from Service endpoints
3. PreStop hook executes (synchronous)
4. SIGTERM sent to container
5. Container has remaining grace period to exit
6. SIGKILL sent if still running

Kubernetes adds 2 extra seconds if the grace period is exceeded but hook is still running. After that, forceful termination occurs.

PreStop hooks don't run if:
- Container is already terminated
- Pod is in Failed or Succeeded phase
- Node is forcefully terminated

For zero-downtime deployments, combine preStop with readiness probe failures:

yaml
lifecycle:
  preStop:
    exec:
      command: ["/bin/sh", "-c", "sleep 15"]  # Wait for endpoints to update

This gives load balancers time to stop sending traffic before the container stops.

Frequently asked questions

What does "FailedPreStopHook" mean?
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.
How do I fix "FailedPreStopHook"?
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 causes "FailedPreStopHook"?
PreStop hook exceeds terminationGracePeriodSeconds Hook command has typos or syntax errors Hook script not executable or not found
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