How to fix ProgressDeadlineExceeded in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 262 views

A deployment failed to progress within the specified timeout (progressDeadlineSeconds). This indicates the pods are not becoming ready, likely due to image pull failures, readiness probe failures, resource constraints, or slow application startup. Diagnose the root cause by checking pod logs, then adjust the deadline or fix the underlying issue.

Quick fix

Fixes ProgressDeadlineExceeded

kubectl describe deployment <deployment-name> -n <namespace>
  1. Check deployment status and conditions
  2. Check pod status and events
  3. View pod logs for application errors
  4. Verify container image exists and is accessible
kubernetes — error
kubectl describe deployment <deployment-name> -n <namespace>
ProgressDeadlineExceeded

What this error means

The Kubernetes deployment controller tracks progress when rolling out a new version. If pods don't become ready within progressDeadlineSeconds (default 600 seconds), the deployment is marked with reason: ProgressDeadlineExceeded. This is not an automatic rollback—it's a signal that something is preventing the rollout from succeeding. The condition appears in deployment.status.conditions with type: Progressing and status: False.

Typical symptoms

  • Deployment shows "ProgressDeadlineExceeded" in kubectl get deployments
  • kubectl describe deployment shows condition with reason: ProgressDeadlineExceeded
  • Pods are stuck in Pending, ContainerCreating, or CrashLoopBackOff
  • kubectl rollout status hangs and eventually times out
  • New replica set is created but pods fail to become Ready
  • Previous rollout succeeded but new version will not progress
  • Orchestration tools (ArgoCD, Helm) report deployment failure

Common causes

  1. Container image does not exist or tag is incorrect
  2. Private container registry credentials are missing or wrong
  3. Readiness probe is failing (app not responding or slow to start)
  4. Pod resource requests exceed available cluster resources
  5. Insufficient memory or CPU on any node
  6. Persistent Volume Claim is not bound
  7. Init container is stuck or failing
  8. Application takes longer to start than readiness probe initialDelaySeconds
  9. Node selector or affinity constraints cannot be satisfied
  10. Container port is already in use on the node

How to fix "ProgressDeadlineExceeded"

1Check deployment status and conditions

View the deployment condition with more detail:

bash
kubectl describe deployment <deployment-name> -n <namespace>

Look for:
- Condition section showing ProgressDeadlineExceeded
- Message explaining why it failed
- Replicas showing how many are desired vs. ready

2Check pod status and events

Inspect the pods created by the deployment:

bash
kubectl get pods -n <namespace> -l app=<label>
kubectl describe pod <pod-name> -n <namespace>

Look at:
- Pod phase (Pending, ContainerCreating, Running, Failed)
- Events section (shows image pull errors, probe failures, etc.)
- Container state (Waiting reason, exit code if Terminated)

3View pod logs for application errors

Check application logs to see why it's not starting:

bash
# View current logs
kubectl logs <pod-name> -n <namespace>

# View previous attempt if pod restarted
kubectl logs <pod-name> --previous -n <namespace>

# Stream logs as they appear
kubectl logs -f <pod-name> -n <namespace>

Common issues: connection timeouts, missing dependencies, config errors.

4Verify container image exists and is accessible

Test image pull from your machine:

bash
docker pull <image:tag>

# For private registries
echo $PASSWORD | docker login -u $USER --password-stdin <registry>
docker pull <registry>/<image:tag>

If it fails, check:
- Image name and tag spelling
- Registry URL
- Private registry credentials
- Image exists in the registry

5Create imagePullSecrets for private registries

If using a private container registry:

bash
kubectl create secret docker-registry regcred \
  --docker-server=<registry> \
  --docker-username=<user> \
  --docker-password=<password> \
  -n <namespace>

Then add to your deployment spec:

yaml
spec:
  template:
    spec:
      imagePullSecrets:
      - name: regcred
6Check readiness probe configuration

Verify the readiness probe is configured correctly:

bash
kubectl get pod <pod-name> -n <namespace> -o yaml | grep -A 20 "readinessProbe"

Common issues:
- initialDelaySeconds is too low (app needs more time to start)
- timeoutSeconds is too low
- Probe is checking the wrong endpoint or port
- Application is not responding on the configured path

Increase initialDelaySeconds if app startup is slow:

yaml
readinessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
7Verify resource availability

Check if pods have enough CPU and memory:

bash
kubectl describe pod <pod-name> -n <namespace> | grep -A 5 "Requests"
kubectl describe nodes | grep -B 5 -A 5 "Allocated resources"

If resources are insufficient, either:
- Reduce pod resource requests in the deployment
- Add more nodes to the cluster
- Delete other pods to free resources
- Increase node capacity

8Increase progressDeadlineSeconds if needed

If the underlying issue is slow but legitimate startup:

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: <deployment-name>
spec:
  progressDeadlineSeconds: 1200  # 20 minutes instead of 10
  template:
    spec:
      containers:
      - name: app
        image: <image:tag>

Apply the change:

bash
kubectl apply -f deployment.yaml

NOTE: Only increase this after fixing the root cause. A high deadline on a broken deployment wastes time.

Advanced notes

ProgressDeadlineExceeded is not a fatal condition—Kubernetes will keep retrying the rollout indefinitely unless you pause the deployment. You can safely pause a deployment and resume it without triggering the deadline timer. Use kubectl rollout pause <deployment> and kubectl rollout resume <deployment>. The progressDeadlineSeconds must be greater than minReadySeconds if both are specified. For CI/CD pipelines, increase timeout appropriately or fix deployment before applying. In some cases, the deadline may be exceeded before readiness probes even run if there's an image pull delay.

Frequently asked questions

What does "ProgressDeadlineExceeded" mean?
The Kubernetes deployment controller tracks progress when rolling out a new version. If pods don't become ready within progressDeadlineSeconds (default 600 seconds), the deployment is marked with reason: ProgressDeadlineExceeded. This is not an automatic rollback—it's a signal that something is preventing the rollout from succeeding.
How do I fix "ProgressDeadlineExceeded"?
A deployment failed to progress within the specified timeout (progressDeadlineSeconds). This indicates the pods are not becoming ready, likely due to image pull failures, readiness probe failures, resource constraints, or slow application startup. Diagnose the root cause by checking pod logs, then adjust the deadline or fix the underlying issue.
What causes "ProgressDeadlineExceeded"?
Container image does not exist or tag is incorrect Private container registry credentials are missing or wrong Readiness probe is failing (app not responding or slow to start)
Is the "ProgressDeadlineExceeded" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading