How to fix MinimumReplicasUnavailable in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 258 views

The MinimumReplicasUnavailable condition indicates your Kubernetes Deployment cannot maintain the minimum required number of available replicas. This blocks rolling updates and signals underlying issues with pod scheduling, resource availability, or container health.

Quick fix

Fixes MinimumReplicasUnavailable

kubectl get pods -o wide
kubectl get events --sort-by='.lastTimestamp'
  1. Get detailed deployment status
  2. Check if pods are pending due to resources
  3. Diagnose pod failures
  4. Adjust health probe settings
kubernetes — error
kubectl get pods -o wide
kubectl get events --sort-by='.lastTimestamp'
MinimumReplicasUnavailable

What this error means

MinimumReplicasUnavailable is a Deployment condition that appears when fewer replicas are running and ready than the configured minimum needed for availability. A pod is considered "available" only when it has been ready for at least `minReadySeconds` (default 0). This condition prevents rolling updates and indicates your deployment is unhealthy. Unlike pod errors (CrashLoopBackOff), this is a deployment-level health indicator. It means the Deployment controller cannot schedule or run the required number of pods, blocking new deployments until the issue is resolved.

Typical symptoms

  • kubectl get deployment shows unequal replicas (e.g., "3/3 desired but 0/3 ready")
  • Pods stuck in Pending, ImagePullBackOff, or CrashLoopBackOff states
  • Rolling updates blocked or progressing very slowly
  • Cluster events show repeated pod failures or eviction denials
  • Logs show liveness/readiness probe failures with timeouts
  • Resource warnings in node descriptions (CPU/memory pressure)
  • Deployment status shows "Waiting for rollout to finish"

Common causes

  1. Insufficient cluster resources (CPU, memory, or disk quota exhausted)
  2. Image pull failures (registry authentication issues, incorrect image references, network problems)
  3. Failing health checks (liveness probes timing out, readiness probes returning errors)
  4. Pod constraints preventing scheduling (nodeName pointing to non-existent nodes, node affinity/anti-affinity rules)
  5. Pod Disruption Budgets (PDB) with overly restrictive minAvailable settings blocking evictions
  6. Security or RBAC issues (insufficient service account permissions, security policies)
  7. Persistent Volume binding failures (PVC not binding to PV in stateful deployments)

How to fix "MinimumReplicasUnavailable"

1Get detailed deployment status

Run kubectl describe deployment <deployment-name> to see conditions and recent events. Look for the Conditions section which shows MinimumReplicasUnavailable details. Also check pod status:

bash
kubectl get pods -o wide
kubectl get events --sort-by='.lastTimestamp'

These show which pods are failing and why.

2Check if pods are pending due to resources

Verify cluster has available resources:

bash
kubectl top nodes  # Shows CPU/memory usage
kubectl describe nodes  # Shows resource allocations and pressures
kubectl get resourcequota -A  # Check namespace quotas

If nodes show CPU/memory pressure or pods are Pending, your cluster is resource-constrained. Either increase node capacity or reduce resource requests in the deployment spec.

3Diagnose pod failures

For pods in ImagePullBackOff, CrashLoopBackOff, or other failure states:

bash
kubectl describe pod <pod-name>
kubectl logs <pod-name>  # Application logs
kubectl logs <pod-name> --previous  # Logs from crash

Common issues:
- ImagePullBackOff: Verify image name, tag, registry credentials
- CrashLoopBackOff: Check application logs for startup errors
- Pending: Check events—usually resource constraints or node affinity conflicts

4Adjust health probe settings

If pods are crashing due to probe failures, make probes more lenient:

yaml
spec:
  containers:
  - name: app
    readinessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 30  # Wait 30s before first check
      timeoutSeconds: 5         # Allow 5s for response
      periodSeconds: 10         # Check every 10s
      failureThreshold: 3       # Fail after 3 failures
    livenessProbe:
      httpGet:
        path: /live
        port: 8080
      initialDelaySeconds: 60
      timeoutSeconds: 5
      periodSeconds: 15
      failureThreshold: 3

Increase initialDelaySeconds if your app takes time to start.

5Verify image accessibility

If using a private registry:

yaml
spec:
  imagePullSecrets:
  - name: regcred  # Must exist: kubectl create secret docker-registry regcred ...
  containers:
  - name: app
    image: private-registry.com/myapp:latest

For public images, verify the tag exists:

bash
docker pull myapp:tag

Check imagePullSecrets exist: kubectl get secret regcred (output should show the secret).

6Review and adjust Pod Disruption Budgets

Check for overly restrictive PDBs:

bash
kubectl get pdb -A
kubectl describe pdb <pdb-name>

If minAvailable is too high, pods cannot be evicted during cluster operations. Consider using maxUnavailable instead:

yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: app-pdb
spec:
  maxUnavailable: 1  # Allow 1 pod unavailable during disruptions
  selector:
    matchLabels:
      app: myapp
7Fix node and affinity constraints

Check for hardcoded node constraints:

bash
kubectl get pod <pod-name> -o yaml | grep -A5 nodeSelector

If nodeName is set to a non-existent node, remove it. For affinity rules, verify they're feasible:

yaml
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
      - matchExpressions:
        - key: disktype
          operator: In
          values:
          - ssd  # Verify at least one node has this label

Check available node labels: kubectl get nodes --show-labels.

Advanced notes

For PVC binding issues in stateful deployments, verify the storage class exists and provisioner is healthy: kubectl get storageclass and kubectl describe pvc <pvc-name>. In multi-tenant clusters, namespace resource quotas may prevent pod creation—use kubectl describe quota to check. For Kubernetes on Docker Desktop or Minikube, resources are extremely limited; reduce replica counts or allocate more memory to the Docker daemon. On GCP/EKS/AKS, check cloud-specific quota limits (project quotas, service quotas). CI/CD deployments should ensure image pull secrets are mounted and registry timeouts are configured. WSL2 may have file system sync delays blocking PVC binding—ensure mounted volumes have sufficient permissions.

Frequently asked questions

What does "MinimumReplicasUnavailable" mean?
MinimumReplicasUnavailable is a Deployment condition that appears when fewer replicas are running and ready than the configured minimum needed for availability. A pod is considered "available" only when it has been ready for at least minReadySeconds (default 0). This condition prevents rolling updates and indicates your deployment is unhealthy.
How do I fix "MinimumReplicasUnavailable"?
The MinimumReplicasUnavailable condition indicates your Kubernetes Deployment cannot maintain the minimum required number of available replicas. This blocks rolling updates and signals underlying issues with pod scheduling, resource availability, or container health.
What causes "MinimumReplicasUnavailable"?
Insufficient cluster resources (CPU, memory, or disk quota exhausted) Image pull failures (registry authentication issues, incorrect image references, network problems) Failing health checks (liveness probes timing out, readiness probes returning errors)
Is the "MinimumReplicasUnavailable" 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