Pod Pending: "0/1 nodes are available: 1 node(s) had untolerated taint"

The scheduler found a node but refuses to use it: the node carries a taint your pod doesn't tolerate. Read which taint, then decide: tolerate it, remove it, or add the right node.

What you'll see

Root causes

Control-plane taint on small clusters

Control-plane nodes carry node-role.kubernetes.io/control-plane:NoSchedule — correct isolation on shared nodes, but on single-node clusters it blocks everything.

Intentional workload isolation taints

Teams taint GPU/memory nodes so only labeled workloads land there. Your pod needs a matching toleration (and often nodeSelector/affinity to land on the right node).

Leftover taints from drain/repair

node.kubernetes.io/unschedulable or a drain taint that was never removed after maintenance. kubectl describe node shows current taints.

Fix it

  1. See the exact taint and current node state
    kubectl get pods -o wide | head ; kubectl describe node <n> | grep -A5 Taints
  2. Choose: tolerate the taint (if safe) on the pod
    # spec.template.spec.tolerations: [{ key: "node-role.kubernetes.io/control-plane", operator: "Exists", effect: "NoSchedule" }]
  3. Or remove the taint when it was left behind
    kubectl taint nodes <n> node.kubernetes.io/unschedulable-  # trailing '-' removes
  4. Keep isolation when intended: add toleration + nodeSelector together
    # tolerations + nodeSelector: { disktype: gpu }   # tolerate AND target the node deliberately

Field note

Single-node/k3s homelab clusters: tolerating the control-plane taint is normal and safe; multi-node clusters should keep control-plane isolation. Taints and tolerations allow; nodeSelector/affinity chooses. Isolation usually needs both directions.

Common questions

What's the difference between a taint and a nodeSelector?

Taints repel pods without matching tolerations; selectors attract pods to labeled nodes. To dedicate a node you typically do both — taint it (repel everyone else) and select it in your pod spec (attract yours).

Is tolerating the control-plane taint safe?

On single-node clusters, yes — there's nothing else to protect. On clusters with dedicated workers, keep control-plane isolation: your workload competes with etcd/apiserver for resources.

Ship it right the first time

Kustomize base with probes, PDBs, and zero-downtime rollouts already wired.

Kubernetes Production Blueprints — $27 →

One-time. Yours to modify. Instant download from the NinjaOps template store.