EC
Pending (PodAffinityError)
KubernetesWARNINGNotableSchedulingHIGH confidence

Pod affinity or anti-affinity rules cannot be satisfied

Production Risk

Scale-out deployments may be unable to place additional replicas.

What this means

This scheduling failure occurs when a pod's podAffinity or podAntiAffinity rules cannot be satisfied. Required (hard) affinity rules block scheduling entirely; preferred (soft) rules are advisory only. Common causes include anti-affinity rules that prevent multiple replicas from fitting on the available nodes, or affinity rules requiring co-location with pods that do not exist.

Why it happens
  1. 1podAntiAffinity required rule prevents replicas from sharing nodes, but there are fewer nodes than replicas
  2. 2podAffinity required rule references pods that do not exist or have different labels
  3. 3Topology key in the affinity rule does not match a label present on nodes
How to reproduce

Pod is Pending with FailedScheduling event mentioning affinity constraints.

trigger — this will error
trigger — this will error
kubectl describe pod mypod | grep -A 10 "Events:"
# Warning  FailedScheduling  0/3 nodes are available:
#   3 node(s) didn't match pod affinity rules,
#   3 node(s) didn't match pod anti-affinity rules.

expected output

Warning  FailedScheduling  ...  3 node(s) didn't match pod anti-affinity rules.

Fix 1

Review affinity rules and node count

WHEN Anti-affinity prevents scheduling

Review affinity rules and node count
kubectl get pod mypod -o yaml | grep -A 30 affinity:
# Ensure replica count does not exceed node count for hard anti-affinity
kubectl get nodes --no-headers | wc -l

Why this works

Hard anti-affinity requires one node per pod replica; replica count must not exceed node count.

Fix 2

Convert hard affinity to soft (preferred)

WHEN Strict co-location or spread is not truly required

Convert hard affinity to soft (preferred)
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:  # soft, not required
    - weight: 100
      podAffinityTerm:
        labelSelector:
          matchLabels:
            app: myapp
        topologyKey: kubernetes.io/hostname

Why this works

preferredDuring rules allow scheduling even when the constraint cannot be satisfied.

Sources
Official documentation ↗

Kubernetes Documentation

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Kubernetes errors