FailedScheduling
This error occurs when the Kubernetes scheduler cannot assign a Pod to any worker node due to filters mismatch, taints, or resource pressure.
Usually happens because:
- ☑ No node matches the nodeSelector or nodeAffinity rules set inside the Pod
- ☑ Multiple Pod replicas request identical static hostPort assignments
- ☑ All nodes suffer from DiskPressure or MemoryPressure conditions
🔍 Quick Checklist:
What is FailedScheduling?
A 'FailedScheduling' event is emitted by the kube-scheduler when it fails to find any worker node that satisfies all criteria required by the Pod's configuration. In Kubernetes v1.36 scheduling frameworks, this process involves filtering nodes (predicates) and scoring them (priorities). Typical triggers include node selector mismatches, taints without matching tolerations, pod affinity/anti-affinity conflicts, or nodes suffering from DiskPressure, PidPressure, or MemoryPressure.
Common Causes
- Node selector or affinity mismatch: The Pod spec requires specific labels (e.g. 'kubernetes.io/os: windows') that do not match active node attributes.
- Host port conflicts: The Pod requests a static 'hostPort' that is already bound by another container running on the node.
- Node condition pressure taints: Worker nodes have transitioned to unhealthy states like 'DiskPressure' or 'NetworkUnavailable', blocking new schedulings.
| Cause | Frequency |
|---|---|
| Unsatisfied Node Selector or Node Affinity filters | ⭐⭐⭐⭐⭐ |
| HostPort conflicts (multiple pods requesting same host port) | ⭐⭐⭐⭐ |
| Target nodes are under DiskPressure or PidPressure | ⭐⭐⭐ |
Common Mistakes
- Setting hard pod anti-affinity configurations (`requiredDuringSchedulingIgnoredDuringExecution`) for replicas exceeding the total count of worker nodes, locking extra replicas in FailedScheduling state.
- Using outdated Node Selector strings referencing deprecated node labels.
How to Fix
Kubernetes Operations & Verification
Establish preferred scheduling rules instead of hard constraints to permit fallback scheduling if ideal nodes are full.
apiVersion: apps/v1
kind: Deployment
metadata:
name: soft-affinity-app
spec:
replicas: 2
template:
spec:
affinity:
nodeAffinity:
# preferred... makes scheduling a preference, not a hard blocking filter
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
preference:
matchExpressions:
- key: disktype
operator: In
values:
- ssd
containers:
- name: web-app
image: nginx:latestPlatform Specific Fixes
List node conditions to identify disk or memory pressures blocking scheduling.
# Query node status conditions list
kubectl get nodes -o custom-columns=NAME:.metadata.name,DISK_PRESSURE:.status.conditions[?(@.type=="DiskPressure")].status,MEM_PRESSURE:.status.conditions[?(@.type=="MemoryPressure")].statusBest Practices
- Configure Pod Topology Spread Constraints with `whenUnsatisfiable: ScheduleAnyway` fallback options.
- Utilize node taint tolerations systematically on system management daemonsets.
Frequently Asked Questions (FAQ)
Q: What is FailedScheduling?
It is an event emitted by the kube-scheduler when a Pod cannot be assigned to any node. This causes the Pod to remain in 'Pending' status.
Q: How does FailedScheduling differ from Pending Pod?
'Pending' is the high-level Pod status. 'FailedScheduling' is the specific Event emitted by the scheduler explaining why the Pod is pending.
Q: How do I troubleshoot '0/3 nodes are available: 3 node(s) had untolerated taint'?
This means the nodes have taints (restrictive labels) that your Pod doesn't tolerate. Add a matching 'tolerations' section to your Pod spec, or verify if you accidentally scheduled workload on the control-plane nodes.
Q: Why do hostPort conflicts block scheduling?
If you specify 'hostPort: 80', only one Pod requesting this port can run on any single node. If you have more replica Pods than nodes, the extra Pods will trigger FailedScheduling. Use a Service instead.