How to fix Waiting for rollout to finish in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 387 views

The "Waiting for rollout to finish" message appears when kubectl rollout status cannot complete a deployment rollout within the expected timeframe. This blocks CI/CD pipelines and indicates your deployment is stuck due to pod failures, resource constraints, or timeout issues.

Quick fix

Fixes Waiting for rollout to finish

kubectl rollout status deployment/<name>
kubectl describe deployment <name>
kubectl get pods -o wide
kubectl get events -n <namespace> --sort-by='.lastTimestamp'
  1. Check current rollout status and pod conditions
  2. Inspect failing pod details
  3. Verify cluster and node resources
  4. Increase progress deadline timeout
kubernetes — error
kubectl rollout status deployment/<name>
kubectl describe deployment <name>
kubectl get pods -o wide
kubectl get events -n <namespace> --sort-by='.lastTimestamp'
Waiting for rollout to finish

What this error means

When you run `kubectl rollout status deployment/<name>`, kubectl waits for all new replicas to become ready and old replicas to be terminated. If this doesn't complete, you see "Waiting for rollout to finish" with the current replica counts (e.g., "2 of 3 updated replicas are available"). This happens when new pods fail to start, old pods don't shut down, or progress exceeds the `progressDeadlineSeconds` timeout (default 10 minutes). The rollout is blocked at the pod level—either new pods aren't becoming ready, or old replicas aren't being replaced.

Typical symptoms

  • kubectl rollout status command hangs or times out
  • Error messages show: "Waiting for rollout to finish: 2 of 3 updated replicas are available..."
  • READY column shows fewer replicas than desired (e.g., "0/3 ready")
  • Pods remain stuck in Pending, ImagePullBackOff, or CrashLoopBackOff states
  • Helm chart installations report rollout failures during upgrades
  • CI/CD pipelines timeout waiting for deployment verification
  • Old pods don't terminate, preventing new pods from starting

Common causes

  1. Insufficient cluster resources (CPU, memory, disk) preventing pod scheduling
  2. Image pull failures (invalid tags, missing credentials, registry connectivity)
  3. Pod startup failures (containers crashing, health checks failing)
  4. Progress deadline exceeded (default 600 seconds) before readiness achieved
  5. Old replicas not terminating (preStop hooks hanging, long graceful shutdown)
  6. Node pressure (memory, disk, PID pressure) preventing scheduling
  7. Health probes (readiness/liveness) timing out or returning errors

How to fix "Waiting for rollout to finish"

1Check current rollout status and pod conditions

Get detailed information:

bash
kubectl rollout status deployment/<name>
kubectl describe deployment <name>
kubectl get pods -o wide
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

Look for pods in Pending, ImagePullBackOff, or CrashLoopBackOff. The Events section shows why pods aren't starting.

2Inspect failing pod details

For each non-running pod:

bash
kubectl describe pod <pod-name>
kubectl logs <pod-name>
kubectl logs <pod-name> --previous  # If crashed, see previous logs

Common issues shown in describe output:
- "Pending": Check "Events" section for resource/scheduling issues
- "ImagePullBackOff": Image pull secret missing or credentials wrong
- "CrashLoopBackOff": Application exits immediately (see logs)
- "Not Ready": Readiness probe failing

3Verify cluster and node resources

Check if resource constraints are blocking:

bash
kubectl top nodes
kubectl describe nodes
kubectl top pods -n <namespace>

Look for:
- CPU/memory pressure on nodes
- "Insufficient cpu" or "Insufficient memory" in pod events
- Disk pressure preventing pod scheduling

If constrained, scale down other deployments or add nodes.

4Increase progress deadline timeout

If rollout takes longer than 10 minutes (default progressDeadlineSeconds), extend it:

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  progressDeadlineSeconds: 1800  # 30 minutes
  # ... rest of spec

Apply: kubectl apply -f deployment.yaml. This doesn't fix the issue but gives slow rollouts time to complete.

5Check and increase health probe timeouts

If readiness probes are timing out, make them more lenient:

yaml
spec:
  containers:
  - name: app
    readinessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 30  # Wait before first check
      timeoutSeconds: 5
      periodSeconds: 10
      failureThreshold: 3

Increase initialDelaySeconds to allow app startup time. Test probe locally:

bash
kubectl exec -it <pod> -- curl http://localhost:8080/health
6Verify image exists and is accessible

Check image configuration:

bash
kubectl get deploy <name> -o yaml | grep -A2 image:

Test pull:

bash
docker pull <image:tag>

For private registries, ensure imagePullSecrets exist:

bash
kubectl get secret <secret-name>
kubectl describe secret <secret-name>

Create if missing:

bash
kubectl create secret docker-registry regcred \
  --docker-server=myregistry.com \
  --docker-username=user \
  --docker-password=pass
7Check preStop hooks and graceful shutdown

If old pods don't terminate, preStop hooks may be hanging:

yaml
spec:
  containers:
  - name: app
    lifecycle:
      preStop:
        exec:
          command: ["/bin/sh", "-c", "sleep 15"]

Review current setup:

bash
kubectl get deploy <name> -o yaml | grep -A10 lifecycle:

Make sure preStop commands complete quickly. Also check terminationGracePeriodSeconds (default 30s):

yaml
spec:
  terminationGracePeriodSeconds: 60  # Increase if cleanup takes time
8Force rollout restart if stuck

If the rollout is completely blocked, restart the deployment:

bash
kubectl rollout restart deployment/<name>

This terminates old pods and starts fresh replicas. Monitor:

bash
kubectl rollout status deployment/<name>

If this also hangs, the issue is pod-level (resource/image/probe), not rollout-specific.

9Monitor in detail with watch

Track rollout progress in real-time:

bash
kubectl get pods -n <namespace> -w  # Watch mode, updates live

In another terminal:

bash
kubectl describe pod <pod-name>  # See latest events

Watch for status changes: Pending → Running → Ready. If pod stays Pending, check node describe output for "Insufficient" messages.

Advanced notes

In Docker Desktop Kubernetes or Minikube with limited resources, consider reducing replica count for testing: kubectl scale deployment <name> --replicas=1. For Helm upgrades, set --wait flag to monitor rollout automatically: helm upgrade <release> <chart> --wait. In CI/CD (GitHub Actions, GitLab CI), increase pipeline timeout to match Kubernetes progressDeadlineSeconds. For slow applications, readiness probes may need 30+ seconds initialDelay. WSL2 may have slower disk I/O affecting image pulls and pod startup—increase timeouts accordingly. Multi-zone clusters may have inter-zone latency affecting pod scheduling. ArgoCD and Flux can monitor rollout completion with Argo notification plugins.

Frequently asked questions

What does "Waiting for rollout to finish" mean?
When you run kubectl rollout status deployment/<name>, kubectl waits for all new replicas to become ready and old replicas to be terminated. , "2 of 3 updated replicas are available"). This happens when new pods fail to start, old pods don't shut down, or progress exceeds the progressDeadlineSeconds timeout (default 10 minutes).
How do I fix "Waiting for rollout to finish"?
The "Waiting for rollout to finish" message appears when kubectl rollout status cannot complete a deployment rollout within the expected timeframe. This blocks CI/CD pipelines and indicates your deployment is stuck due to pod failures, resource constraints, or timeout issues.
What causes "Waiting for rollout to finish"?
Insufficient cluster resources (CPU, memory, disk) preventing pod scheduling Image pull failures (invalid tags, missing credentials, registry connectivity) Pod startup failures (containers crashing, health checks failing)
Is the "Waiting for rollout to finish" 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