How to fix ReplicaFailure in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 210 views

ReplicaFailure indicates that the Kubernetes ReplicaSet controller cannot create or maintain the desired number of pod replicas. This is usually caused by resource constraints, image pull errors, or security policy violations that prevent pod creation.

Quick fix

Fixes ReplicaFailure

kubectl describe quota -n <namespace>
kubectl describe resourcequota -n <namespace>
  1. Check namespace resource quotas
  2. Inspect ReplicaSet for detailed errors
  3. Verify container image exists and is accessible
  4. Check pod specification for errors
kubernetes — error
kubectl describe quota -n <namespace>
kubectl describe resourcequota -n <namespace>
ReplicaFailure

What this error means

ReplicaFailure is a Deployment condition that appears when the ReplicaSet controller repeatedly fails to create new pods. When you describe a deployment with this condition, you'll see `Type: ReplicaFailure, Status: True, Reason: FailedCreate`. The ReplicaSet wants to create pods but something is blocking creation—either the pod specification is invalid, resources are exhausted, or admission controllers are rejecting the pods. This is different from pods failing after creation (CrashLoopBackOff). ReplicaFailure means the pods never get created in the first place.

Typical symptoms

  • Deployment stuck in pending state with no progress
  • Pods fail to transition from Pending to Running
  • kubectl describe deployment shows: "Type: ReplicaFailure, Status: True, Reason: FailedCreate"
  • Events section missing or showing only controller attempts without detailed error messages
  • Some replicas run successfully while others fail intermittently
  • Rolling updates blocked, unable to create new replica sets
  • kubectl logs shows no application errors (pods aren't even created)

Common causes

  1. Namespace CPU/memory quotas exceeded (most common cause)
  2. Container image cannot be fetched from registry (pull errors)
  3. Readiness/liveness probe failures preventing pod readiness
  4. Security context constraints or Pod Security Policies rejecting pods
  5. RBAC permissions issues with service account
  6. Namespace resource limit ranges violated by pod specifications
  7. Pod specification with invalid syntax or missing required fields
  8. Istio or other sidecar injection failures
  9. Unsafe sysctls not whitelisted in cluster configuration
  10. Network connectivity issues between control plane and worker nodes

How to fix "ReplicaFailure"

1Check namespace resource quotas

This is the most common cause. Run:

bash
kubectl describe quota -n <namespace>
kubectl describe resourcequota -n <namespace>

Look at Used vs Limit columns. If requests are at or near the limit, that's blocking new pods. Either scale down other deployments or increase the quota:

bash
kubectl edit resourcequota <quota-name> -n <namespace>
# Increase the limits for cpu, memory, and pods
2Inspect ReplicaSet for detailed errors

Get more information than the Deployment:

bash
kubectl get replicaset -n <namespace>
kubectl describe replicaset <rs-name> -n <namespace>

The Events section at the bottom shows the actual error. Common ones:
- "Insufficient cpu": Pod requests exceed available resources
- "pod already exists": State inconsistency
- "Pod creation blocked": Admission controller rejection (PodSecurityPolicy, Istio, custom webhooks)

3Verify container image exists and is accessible

Check the image reference in your deployment:

bash
kubectl get deploy <name> -o yaml | grep -A2 image:

Verify the image exists:

bash
docker pull myregistry.com/myimage:tag

For private registries, verify imagePullSecrets:

yaml
spec:
  imagePullSecrets:
  - name: regcred  # Must match a valid secret
  containers:
  - image: private.registry/image:tag

Create if missing: kubectl create secret docker-registry regcred --docker-server=... --docker-username=... --docker-password=...

4Check pod specification for errors

Validate your deployment YAML:

bash
kubectl apply -f deployment.yaml --dry-run=client

Common issues:
- typos in field names
- invalid resource requests (e.g., "100G" instead of "100Gi")
- missing or malformed probe configurations
- invalid security contexts

Get current spec to review: kubectl get deploy <name> -o yaml

5Verify cluster has available resources

Check overall cluster capacity:

bash
kubectl top nodes
kubectl describe nodes
kubectl get --raw /api/v1/namespaces/<ns>/pods

If all nodes show CPU/memory pressure, the cluster is full. Solutions:
- Scale down other deployments
- Add more worker nodes
- Reduce resource requests in your pod spec

For resource requests, check current deployment:

bash
kubectl get deploy <name> -o yaml | grep -A5 resources:
6Verify service account and RBAC permissions

Check the service account:

bash
kubectl get sa -n <namespace>
kubectl describe sa <sa-name> -n <namespace>

Verify RBAC bindings allow pod creation:

bash
kubectl get rolebindings,clusterrolebindings -n <namespace> -o wide

If missing, create a role with pod creation permissions:

yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: pod-creator
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["create", "get", "list"]
7Check for admission webhook rejections

If using Istio, service mesh, or custom admission webhooks, they may be rejecting pods:

bash
kubectl get validatingwebhookconfigurations
kubectl get mutatingwebhookconfigurations

Describe to see rules:

bash
kubectl describe validatingwebhookconfigurations <name>

Check admission controller logs:

bash
kubectl logs -n istio-system deployment/istiod  # For Istio
kubectl logs -n kube-system <admission-pod>     # For custom controllers
8Increase progress deadline if needed

If everything looks correct but pods take time to schedule, increase the timeout:

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  progressDeadlineSeconds: 1800  # 30 minutes instead of default 10
  # ... rest of spec

Apply: kubectl apply -f deployment.yaml

Advanced notes

In Docker Desktop's limited single-node cluster, resource quotas are common bottlenecks—try removing or increasing them. For Minikube, allocate more CPUs/memory at startup. In multi-node clusters, uneven resource distribution may schedule pods on under-resourced nodes despite overall available resources. Limit Range violations are similar to quota issues but apply per-pod rather than namespace-wide—check with kubectl describe limits. For WSL2-based Kubernetes, ensure adequate disk space and memory in the WSL environment. In GitOps workflows, if deployment was previously working, ReplicaFailure may indicate external changes (quotas modified, admission webhooks added, node resources consumed by other workloads).

Frequently asked questions

What does "ReplicaFailure" mean?
ReplicaFailure is a Deployment condition that appears when the ReplicaSet controller repeatedly fails to create new pods. When you describe a deployment with this condition, you'll see Type: ReplicaFailure, Status: True, Reason: FailedCreate. The ReplicaSet wants to create pods but something is blocking creation—either the pod specification is invalid, resources are exhausted, or admission controllers are rejecting the pods.
How do I fix "ReplicaFailure"?
ReplicaFailure indicates that the Kubernetes ReplicaSet controller cannot create or maintain the desired number of pod replicas. This is usually caused by resource constraints, image pull errors, or security policy violations that prevent pod creation.
What causes "ReplicaFailure"?
Namespace CPU/memory quotas exceeded (most common cause) Container image cannot be fetched from registry (pull errors) Readiness/liveness probe failures preventing pod readiness
Is the "ReplicaFailure" 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