How to fix finalizers stuck on namespace in Kubernetes

KubernetesADVANCEDHIGHUpdated Dec 6, 2025· 168 views

A Kubernetes namespace cannot be deleted because a finalizer is blocking termination. Finalizers ensure cleanup operations complete before a resource is removed.

Quick fix

Fixes finalizers stuck on namespace

kubectl get namespace my-namespace -o yaml
  1. Check what finalizers are blocking the namespace
  2. Check if the finalizer controller is running
  3. Remove the stuck finalizer (force delete)
  4. Verify the namespace is deleted
kubernetes — error
kubectl get namespace my-namespace -o yaml
finalizers stuck on namespace

What this error means

Finalizers are Kubernetes hooks that prevent resource deletion until certain cleanup operations finish. When a namespace has finalizers that don't complete (often due to missing controllers or unresponsive webhooks), the namespace enters a "Terminating" state indefinitely. This commonly happens when a custom resource or operator is removed without cleaning up its finalizers.

Typical symptoms

  • Namespace stuck in Terminating state for hours or days
  • kubectl delete namespace returns but namespace doesn't disappear
  • kubectl get namespace shows Terminating status
  • Finalizers list shows stalled operations
  • Kubernetes API shows foreground deletion in progress
  • Cannot redeploy applications to that namespace

Common causes

  1. Finalizer controller was removed or is not running
  2. Webhook for finalizer is unreachable or broken
  3. Custom operator managing the finalizer was deleted
  4. Network policies blocking finalizer controller
  5. Kubernetes API server issue preventing finalizer cleanup
  6. Orphaned finalizers from deleted Custom Resource Definitions

How to fix "finalizers stuck on namespace"

1Check what finalizers are blocking the namespace

Get details on the terminating namespace:

bash
kubectl get namespace my-namespace -o yaml

Look for the finalizers list under metadata. Common ones include:
- kubernetes
- foregroundDeletion
- Custom finalizers like myoperator.io/cleanup

2Check if the finalizer controller is running

If the finalizer comes from an operator, verify it's deployed:

bash
kubectl get deployment -A | grep -i operator-name

If the operator is missing or stuck, that's the problem.

3Remove the stuck finalizer (force delete)

Extract the namespace YAML without finalizers:

bash
kubectl get namespace my-namespace -o json | jq 'del(.metadata.finalizers)' | kubectl replace --raw /api/v1/namespaces/my-namespace -f -

Or edit directly:

bash
kubectl edit namespace my-namespace
# Remove the finalizers array entirely
4Verify the namespace is deleted

After removing finalizers, the namespace should delete immediately:

bash
kubectl get namespace my-namespace
# Should show: No resources found
5Prevent future stuck finalizers

For operators you deploy, ensure they have proper cleanup:

bash
# Before removing an operator, clean up its finalizers
kubectl delete crds $(kubectl get crds --all-namespaces -o name | grep myoperator.io)

# Or restart the operator to let it clean up gracefully
kubectl rollout restart deployment/my-operator -n operators

Advanced notes

Use kubectl patch to remove finalizers on live resources: kubectl patch namespace my-namespace -p '{"metadata":{"finalizers":null}}'. Finalizerscannot be completely avoided, but operators should implement proper cleanup logic. Use admission webhooks carefully—a failing webhook can block namespace deletion. In production, monitor finalizer operations and set timeouts on long-running cleanup tasks.

Frequently asked questions

What does "finalizers stuck on namespace" mean?
Finalizers are Kubernetes hooks that prevent resource deletion until certain cleanup operations finish. When a namespace has finalizers that don't complete (often due to missing controllers or unresponsive webhooks), the namespace enters a "Terminating" state indefinitely. This commonly happens when a custom resource or operator is removed without cleaning up its finalizers.
How do I fix "finalizers stuck on namespace"?
A Kubernetes namespace cannot be deleted because a finalizer is blocking termination. Finalizers ensure cleanup operations complete before a resource is removed.
What causes "finalizers stuck on namespace"?
Finalizer controller was removed or is not running Webhook for finalizer is unreachable or broken Custom operator managing the finalizer was deleted
Is the "finalizers stuck on namespace" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading