# Kubernetes "topology spread constraints" Unsatisfiable in CI

> Fix Kubernetes "didn't match pod topology spread constraints" FailedScheduling in CI - DoNotSchedule with maxSkew too tight for the number of available topology domains.

Source: https://latchkey.dev/learn/kubernetes/k8s-topologyspreadconstraints-unsatisfiable  
Updated: 2026-06-25

A `topologySpreadConstraints` rule with `whenUnsatisfiable: DoNotSchedule` keeps pods Pending when there are not enough topology domains (zones/nodes) to honor `maxSkew`. The scheduler refuses to place a pod that would violate the spread.

## Diagnose it: read events, not just status

A deployment that never becomes ready has the reason in its events and in the pod state, not in the deployment status. Read both before changing the manifest.

```Terminal
kubectl rollout status deploy/<name> --timeout=120s
kubectl describe deploy/<name> | sed -n "/Events/,$p"
kubectl get pods -l app=<name> -o wide
kubectl describe pod <pod> | sed -n "/Events/,$p"
kubectl logs <pod> --previous --tail=50   # the crash before the restart
```

> `--previous` gives you the logs of the container that died, which is the one that explains a CrashLoopBackOff. The current container is usually still starting and tells you nothing.

## FAQ

### What causes Kubernetes "topology spread constraints" unsatisfiable in CI?

There are 2 common causes: too few topology domains for the skew and nodes missing the topology label. Spreading across topology.kubernetes.io/zone with maxSkew: 1 needs enough zones to balance replicas.

### How do I fix Kubernetes "topology spread constraints" unsatisfiable in CI?

There are 2 fixes depending on which cause you have: inspect the domains and the constraint and loosen the constraint or let it degrade gracefully. Work through them in order, since the first is the most common.

### What does Kubernetes "topology spread constraints" unsatisfiable in CI actually mean?

New pods stay Pending with FailedScheduling noting the topology spread constraint.

### How do I stop Kubernetes "topology spread constraints" unsatisfiable in CI happening again?

Match maxSkew/DoNotSchedule to the number of labeled domains you actually run. The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt