Deployment rollout stuck: ProgressDeadlineExceeded
A rollout that stalls reports ProgressDeadlineExceeded. Find why the new ReplicaSet's pods are not ready, then fix it or roll back with kubectl rollout undo.
What you see
kubectl rollout status deployment/NAMEwaits and never finishes- Deployment condition:
type: Progressing,status: "False",reason: ProgressDeadlineExceeded
What it means
A Deployment can get stuck trying to deploy its newest ReplicaSet. The docs list the causes: insufficient quota, readiness probe failures, image pull errors, insufficient permissions, limit ranges, and application runtime misconfiguration.
Kubernetes takes no action on a stalled Deployment except to report the condition after .spec.progressDeadlineSeconds. It does not roll back on its own. The old pods keep serving while the new ones fail, which is the safety net.
How to confirm the cause
- 1Watch the rollout
kubectl rollout status deployment/NAME
- 2Read the Deployment's conditions
kubectl describe deployment NAME
Look for
Progressingand the reason. - 3Look at the new pods, not the old ones
kubectl get pods -l app=NAME
Find pods that are
Pending,ImagePullBackOff,CrashLoopBackOffor not Ready, thenkubectl describe podon one.
Causes and fixes
New pods fail their readiness probe
- HOW TO TELL
- Pods are Running but
0/1Ready. - ROOT CAUSE
- The new version is not answering its readiness check, so the controller never counts it as available.
- FIX
- Fix the app or the probe. See the probe-failures runbook.
New pods cannot start
- HOW TO TELL
ImagePullBackOff,CrashLoopBackOfforPendingon the new pods.- ROOT CAUSE
- The new ReplicaSet has a bad image, bad config, or no room to schedule.
- FIX
- Follow the runbook for the pod status you see.
Quota or limit range blocks the pods
- HOW TO TELL
- Events on the ReplicaSet mention exceeding quota or a limit range.
- ROOT CAUSE
- The namespace's ResourceQuota or LimitRange refuses the new pods, so they are never created.
- FIX
- Raise the quota or fix the requests, then check
kubectl describe replicaset.
How to stop it coming back
- Set
progressDeadlineSecondsso a stall becomes visible. - Have your pipeline run
kubectl rollout statusand fail the deploy on timeout. - Use a canary or staged rollout for risky changes.
Keep going
- Runbook: Liveness probe failed: the container keeps being restarted
- Runbook: ImagePullBackOff: the pod can't pull its image
- Runbook: CrashLoopBackOff: the container keeps crashing
- Cheat sheet: kubectl
- Lesson: the kubernetes topic in Learn
Sources
Kubernetes documentation (kubernetes.io), read 18 Nov 2026. The docs version selector listed v1.33 to v1.37.