Kubernetes Pod Not Ready: Debugging Guide
Step-by-step guide to diagnose and fix pods stuck in NotReady state — the most common Kubernetes issue after CrashLoopBackOff.
Table of Contents
- What "Not Ready" Means
- Diagnostic Workflow
- How Readiness Affects Traffic
- Common Causes and Fixes
- Readiness Probe Deep Dive
- When Readiness Is a Symptom
- Quick Checklist
What "Not Ready" Means
A pod shows 0/1 READY and Running status when containers are up but the readiness probe fails. Traffic will NOT be routed to these pods by Services.
kubectl get pods
# NAME READY STATUS RESTARTS AGE
# my-app-7d4b8c9f-x2abc 0/1 Running 0 5m
Running but not Ready = the app started but can't serve traffic yet.
How Readiness Affects Traffic
The mechanics behind "not Ready": Kubernetes Services select pods by label, but only ready pods get added to the Service's endpoints:
# See which pods are actually getting traffic
kubectl get endpoints <service-name>
# NAME ENDPOINTS
# my-app 10.244.1.5:8080,10.244.1.6:8080
# 3 pods exist but only 2 are in the endpoints — the third isn't Ready
kubectl get pods -l app=my-app
# NAME READY STATUS RESTARTS AGE
# my-app-7d4b8c9f-x2abc 1/1 Running 0 5m
# my-app-7d4b8c9f-y3def 1/1 Running 0 5m
# my-app-7d4b8c9f-z4ghi 0/1 Running 0 3m ← not in endpoints
EndpointSlices (the modern replacement for Endpoints) show the same thing with more detail — kubectl get endpointslice gives per-endpoint readiness, zone, and node topology. A 0/1 pod that is running is a pod that exists but receives zero traffic — the readiness gate is what makes that distinction.
Diagnostic Workflow
Step 1: Describe the Pod
kubectl describe pod my-app-7d4b8c9f-x2abc
Check the Events section at the bottom:
Warning Unhealthy 5s (x10 over 2m) kubelet Readiness probe failed:
Get "http://10.244.1.5:8080/health": dial tcp 10.244.1.5:8080: connect: connection refused
This tells you the exact probe URL failing.
Step 2: Check the Logs
kubectl logs my-app-7d4b8c9f-x2abc
# If the app takes time to boot, follow logs
kubectl logs -f my-app-7d4b8c9f-x2abc
Step 3: Test the Endpoint Manually
# Exec into the pod and test the readiness URL
kubectl exec -it my-app-7d4b8c9f-x2abc -- curl -v localhost:8080/health
# Test with wget if curl isn't installed
kubectl exec -it my-app-7d4b8c9f-x2abc -- wget -qO- localhost:8080/health
Step 4: Check the Probe Configuration
kubectl get pod my-app-7d4b8c9f-x2abc -o yaml | grep -A 10 readinessProbe
Common Causes and Fixes
1. Probe Hits Wrong Port or Path
# WRONG — app listens on 3000, probe checks 8080
readinessProbe:
httpGet:
path: /health
port: 8080
# FIX — match the actual container port
readinessProbe:
httpGet:
path: /health
port: 3000
2. App Needs Longer Startup Time
Java apps, apps loading caches, or apps running migrations can take 60s+ to be ready.
# Give it more time
readinessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 60 # wait before first probe
periodSeconds: 10
failureThreshold: 6 # allow 6 failures (60 more seconds)
Better solution — use a startupProbe for slow starters:
startupProbe:
httpGet:
path: /health
port: 8080
failureThreshold: 30 # 30 × 5s = 150s max startup
periodSeconds: 5
readinessProbe:
httpGet:
path: /ready
port: 8080
periodSeconds: 5
3. Dependency Not Ready (Database, Redis, etc.)
The app can't become ready because a dependency is down.
# Check if the dependency pod is running
kubectl get pods -l app=postgres
# Test connectivity from the app pod
kubectl exec -it my-app-7d4b8c9f-x2abc -- nc -zv postgres-service 5432
Fix: ensure the app's /ready endpoint correctly reflects dependency status, or make the app start serving before dependencies connect.
4. Readiness Endpoint Returns Non-2xx
The endpoint must return HTTP 200–399. Redirects to auth pages (302 → /login) WILL pass since 302 is acceptable — but 500 fails.
# Check what the endpoint actually returns
kubectl exec -it my-app-7d4b8c9f-x2abc -- curl -i localhost:8080/health
5. Resource Starvation
Pod runs but responds too slowly:
# Check if CPU throttling
kubectl top pod my-app-7d4b8c9f-x2abc
kubectl describe pod my-app-7d4b8c9f-x2abc | grep -A3 "QoS"
# Increase limits
resources:
requests:
cpu: "250m"
memory: "256Mi"
limits:
cpu: "500m"
memory: "512Mi"
6. Missing Health Endpoint
If the app has no /health endpoint, either add one or use a TCP probe:
readinessProbe:
tcpSocket:
port: 8080
periodSeconds: 5
A TCP probe passes if the port accepts connections — simpler but less accurate than HTTP.
7. Init Container Still Running
kubectl get pods
# my-app-7d4b8c9f-x2abc 0/1 Init:0/1 0 3m
# Check init container logs
kubectl logs my-app-7d4b8c9f-x2abc -c init-container-name
Readiness Probe Deep Dive
Probe Types
# HTTP probe (most common)
readinessProbe:
httpGet:
path: /ready
port: 8080
httpHeaders:
- name: X-Custom-Header
value: ready
# TCP probe (port connectivity only)
readinessProbe:
tcpSocket:
port: 5432
# Exec probe (run a command)
readinessProbe:
exec:
command:
- sh
- -c
- "pg_isready -U postgres"
Timing Parameters Explained
| Parameter | Meaning | Default |
|---|---|---|
initialDelaySeconds | Wait before first probe | 0 |
periodSeconds | Time between probes | 10 |
timeoutSeconds | Probe timeout | 1 |
successThreshold | Successes needed to mark ready | 1 |
failureThreshold | Failures before not-ready | 3 |
Total max wait = initialDelaySeconds + (failureThreshold × periodSeconds)
Readiness vs Liveness — Critical Difference
| Readiness | Liveness | |
|---|---|---|
| Failure result | Removed from Service endpoints | Container restarted |
| Use for | "Can I serve traffic?" | "Am I deadlocked/crashed?" |
| Typical endpoint | /ready (checks deps) | /health (checks self) |
Never put dependency checks in liveness probes — a database blip would restart all your pods.
When Readiness Is a Symptom
Sometimes the readiness failure is the effect, not the cause:
- CPU throttling — the health endpoint times out because the pod can't get CPU cycles. The probe is correct; the resources are wrong.
- Network policy — a newly added
NetworkPolicyblocked the kubelet's probe path. The probe fails because it can't reach the pod, not because the app is broken. - DNS resolution — the readiness endpoint resolves a service name that CoreDNS can't find (typo in the URL, missing
namespacesuffix). The app is fine; the probe can't resolve the hostname. - Volume mount stuck — a PVC that's still attaching delays the container start past the probe's first check. The pod is
InitorContainerCreating, not truly "not ready" yet.
The pattern: when kubectl describe shows the probe failing consistently but curl inside the pod works, look at what's between the kubelet and the endpoint — network policy, DNS, or the node itself.
Quick Checklist
When a pod shows 0/1 Running:
# 1. Events — what is failing?
kubectl describe pod <name> | tail -20
# 2. Logs — is the app logging errors?
kubectl logs <name> --tail=50
# 3. Probe config — correct port/path?
kubectl get pod <name> -o yaml | grep -A8 readinessProbe
# 4. Manual test — does the endpoint respond?
kubectl exec -it <name> -- curl -i localhost:<port>/<path>
# 5. Resources — throttled?
kubectl top pod <name>
# 6. Dependencies — reachable?
kubectl exec -it <name> -- nc -zv <dependency> <port>
Related Articles
Our tutorials and troubleshooting runbooks are written by a DevOps practitioner with hands-on experience operating Kubernetes, Terraform, CI/CD pipelines, and Linux infrastructure in production. Commands, manifests, and configurations are verified against current tooling releases. Learn more about our editorial process or report a correction or outdated flag.