Skip to content
DevOps AI ToolKit
Newsletter
Kubernetes Troubleshooting Toolkit

Kubernetes Troubleshooting Toolkit

Use this Kubernetes troubleshooting toolkit to diagnose CrashLoopBackOff, ImagePullBackOff, OOMKilled, pending pods, failed scheduling, probe failures, ingress errors, and node problems.

Paste your error and get a triage plan.

Paste a log line, CLI error, stack trace, service failure, or config snippet and get a structured troubleshooting plan. Your snippet is carried straight into the AI Incident Response Assistant with Kubernetes context prefilled.

Open the Kubernetes Incident Assistant → Browse Kubernetes prompts

Do not paste secrets, tokens, private keys, passwords, or customer data. Your snippet stays in your browser until you open the assistant.

Top 25 Kubernetes Errors and Failure Modes

The production failures engineers hit most — each links to a full cause → fix → prevention guide.

CrashLoopBackOff

A container starts, crashes, and Kubernetes keeps restarting it with an increasing back-off delay.

ImagePullBackOff

The kubelet cannot pull the container image and backs off before retrying, leaving the pod unable to start.

ErrImagePull

The initial image pull failed, usually due to a bad image name, tag, or registry authentication.

OOMKilled

The container exceeded its memory limit and was killed by the kernel out-of-memory reaper.

CreateContainerConfigError

The container cannot be created because a referenced ConfigMap, Secret, or env value is missing or invalid.

CreateContainerError

The container runtime failed to create the container, often from a bad command, mount, or runtime issue.

Pending pod

The pod is accepted by the API server but cannot be scheduled onto any node yet.

Evicted pod

The kubelet evicted the pod because the node ran low on memory, disk, or another resource.

Readiness probe failed

The readiness probe is failing so the pod is removed from Service endpoints and receives no traffic.

Liveness probe failed

The liveness probe is failing so the kubelet restarts the container, sometimes causing a restart loop.

Init container failed

An init container exited non-zero, blocking the main containers from ever starting.

ConfigMap not found

A pod references a ConfigMap that does not exist in the namespace, so it cannot be created.

Secret not found

A pod references a Secret that is missing from the namespace, blocking container creation.

Service unavailable

A Service has no ready endpoints, so requests to it fail or time out.

Ingress 404

The ingress controller returns its default backend 404 because no rule matches the request host or path.

Ingress 502

The ingress controller cannot connect to the upstream pod and returns a 502 bad gateway.

DNS resolution failure

In-cluster name lookups fail with no such host, usually a CoreDNS or service-name problem.

Node NotReady

A node reports NotReady, so the scheduler stops placing pods on it and existing pods may be evicted.

PersistentVolumeClaim pending

A PVC cannot bind to a PersistentVolume, leaving pods that mount it stuck in Pending.

MountVolume.SetUp failed

The kubelet failed to mount a volume into the pod, often from a missing secret, config, or storage backend error.

FailedScheduling

The scheduler cannot find a node that satisfies the pod's resource requests, affinity, or taint constraints.

RBAC forbidden

A request is denied because the user or service account lacks the required role or cluster role binding.

Container cannot connect to service

A pod gets connection refused when reaching another service, usually a port, selector, or network-policy issue.

TLS certificate error

A TLS handshake fails because of a bad, expired, or untrusted certificate between components.

Helm upgrade failed

A helm upgrade errors out or leaves the release in a failed or pending state that blocks further changes.

Validate your config before you redeploy

Catch the structural mistakes that cause outages — 100% in your browser, nothing uploaded.

Kubernetes Manifest ValidatorHelm Chart Validator Not sure? Start with the Incident Assistant →

Kubernetes Troubleshooting Hubs

Fix a whole class of Kubernetes errors at once — each hub gathers the related guides for one failure class.

Kubernetes Storage & Volume Errors

Fix Kubernetes storage failures — PVC not bound, multi-attach, FailedMount, CSI deadline exceeded, and volume node-affinity conflicts — with worked diagnostics and copy-paste commands.

Open hub

Kubernetes Pod Startup & CrashLoop Errors

Fix pods that will not start — CrashLoopBackOff, ImagePullBackOff, OOMKilled, CreateContainerConfigError, Init container failures and evictions — with root-cause diagnostics and commands.

Open hub

Kubernetes Networking, DNS & Ingress Errors

Fix Kubernetes networking failures — connection refused in-cluster, CoreDNS SERVFAIL, dial tcp i/o timeout, no endpoints available, ingress 503/413, and CNI setup errors — with exact kubectl commands.

Open hub

Best Kubernetes Prompts

Turn symptoms, logs, and config into a structured plan with prompts tuned for Kubernetes.

CrashLoopBackOff triage

Systematically diagnose a restart-looping pod

Use this prompt

ImagePullBackOff debugging

Track down failed image pulls and registry auth

Use this prompt

OOMKilled memory limit diagnosis

Right-size limits after an out-of-memory kill

Use this prompt

FailedScheduling debug

Explain why a pod won't schedule onto any node

Use this prompt

Pending pod scheduling diagnosis

Unblock a pod stuck in Pending

Use this prompt

Kubernetes YAML security review

Audit manifests for risky or missing settings

Use this prompt

Helm failed upgrade recovery runbook

Recover a stuck or failed Helm release

Use this prompt

Readiness & liveness probe authoring

Design probes that don't cause false restarts

Use this prompt

Download the Kubernetes Troubleshooting Runbook Pack

Pod-failure runbooks for CrashLoopBackOff, ImagePullBackOff, and OOMKilled — events, logs, probes, images, and resource limits.

  • CrashLoopBackOff triage by exit code
  • ImagePullBackOff / registry auth checks
  • OOMKilled limit vs node pressure
  • Probe & scheduling failure steps
  • ConfigMap / Secret / RBAC checks
Download the Kubernetes Runbook Pack

All Kubernetes Troubleshooting Guides

Grouped by failure-mode type — each guide covers cause, fix, validation, and prevention.

Authentication & TLS (12)

permission denied the server has asked for the client to provide credentials no such file /var/run/secrets/.../token x509: certificate is valid for ..., not <svc>.<ns>.svc field is immutable The Certificate Nobody Owned: A Kubernetes TLS War Story forbidden: exceeded quota secret not found Failed to create new replica set ... is forbidden updates to statefulset spec ... are forbidden pull access denied ReplicaFailure: True

Networking (16)

cni config uninitialized failed to allocate for range 0: no IP addresses available Liveness probe failed: ... connection refused Pod sandbox changed, it will be killed and re-created rpc error: code = Unavailable desc = connection error Unable to connect to the server: EOF Ingress '413 Request Entity Too Large' — Fix Upload Limits The Lookup That Only Failed Inside the Pod: A Kubernetes DNS War Story CNI request failed with status 400 connect: connection refused dial tcp <ip>:<port>: i/o timeout 503 Service Temporarily Unavailable upstream connect error or disconnect/reset before headers lookup <svc>.svc.cluster.local: no such host dial tcp <ip>:<port>: connect: no route to host node is unreachable

Storage (12)

Usage of EmptyDir volume exceeds the limit invalid capacity 0 on image filesystem failed to garbage collect required amount of images mount propagation not supported unable to create new content in namespace because it is being terminated node(s) had volume node affinity conflict The Volume That Wouldn't Let Go: A Kubernetes PVC War Story rpc error: code = DeadlineExceeded etcdserver: mvcc: database space exceeded failed to provision volume with StorageClass Warning FailedMount DiskPressure True

Deployment & Builds (7)

metadata.annotations: Too long: must have at most 262144 bytes chart requires kubeVersion container has runAsNonRoot and image will run as root rendered manifests contain a resource that already exists strict decoding error: unknown field Init Container Failed manifest unknown

Runtime (14)

Cannot evict pod as it would violate the pod failed to reserve container name Failed to watch *v1.Pod: unexpected EOF minimum cpu usage per Container Pod Status 'SchedulingGated' — Fix Pods That Never Schedule Pod Stuck 'Terminating' — Fix Pods That Won't Delete Readiness probe failed: statuscode: 503 The Pod That Lied: A Kubernetes Readiness Probe War Story Pod Stuck in Pending failed to create containerd task Failed to list *v1.Pod Error syncing pod No preemption victims found for incoming pod 5 node(s) didn

Performance (4)

etcdserver: too many requests too many open files Client.Timeout exceeded while awaiting headers MemoryPressure True

API errors (5)

v1beta1.metrics.k8s.io: the server is currently unable to handle the request Kubernetes Limits and Requests: A Practical 2026 Guide unable to fetch metrics from resource metrics API Error from server (InternalError) etcdserver: leader changed

Configuration (2)

the server doesn configmap not found

Other (18)

Argo CD vs Flux: Choosing a GitOps Engine for Kubernetes Kubernetes vs Nomad: Choosing a Workload Orchestrator ChatGPT vs Claude for Kubernetes and Docker Support cannot delete Pods not managed by ReplicationController, ReplicaSet, Job, DaemonSet or StatefulSet too old resource version no matches for kind in version violates PodSecurity restricted Kubernetes vs Docker: They Aren't Competitors (Here's What Each Actually Does) SERVFAIL DaemonSet does not have minimum availability Error from server (AlreadyExists) Error from server (Conflict) Error from server (NotFound) failed calling webhook Kubernetes 'Job has reached the specified backoff limit' (BackoffLimitExceeded): Fix Job was active longer than specified deadline PIDPressure True PLEG is not healthy
Browse the full Kubernetes category

Kubernetes troubleshooting FAQ

Why is my pod stuck in CrashLoopBackOff?
CrashLoopBackOff means the container keeps starting and then exiting, so Kubernetes restarts it with a growing back-off delay. Run kubectl logs --previous to see why the last run exited, and kubectl describe pod to check exit codes and events. Common causes are an application error or bad config, a missing environment variable, ConfigMap, or Secret, a failing liveness probe that restarts a healthy app, or a command that runs once and exits instead of staying alive.
How do I fix ImagePullBackOff or ErrImagePull?
Both mean the kubelet could not pull the image; ErrImagePull is the initial failure and ImagePullBackOff is Kubernetes backing off before retrying. Check kubectl describe pod for the exact reason. Usually it is a wrong image name or tag, an image that does not exist in the registry, or missing registry credentials. Verify the repository and tag, confirm the image exists, and add an imagePullSecret if the registry is private.
What does OOMKilled mean and how do I fix it?
OOMKilled means the container exceeded its memory limit and the kernel's out-of-memory killer terminated it (exit code 137). Fix it by measuring real usage and either raising the container's memory limit or reducing the application's memory footprint. Also set memory requests so the scheduler places the pod on a node with enough headroom, and watch for leaks that make usage climb until the limit is hit again.
Why is my pod Pending or showing FailedScheduling?
A Pending pod has been accepted but the scheduler cannot place it on any node. Run kubectl describe pod and read the FailedScheduling events. Typical reasons are insufficient CPU or memory on all nodes, node taints the pod does not tolerate, node affinity or nodeSelector rules that match nothing, or an unbound PersistentVolumeClaim. Free up capacity, adjust requests, or fix the scheduling constraints to let it bind.
When should I use the Kubernetes manifest validator?
Use the Kubernetes manifest validator before applying YAML to catch problems early: malformed YAML, missing required fields, risky settings like running as root or no resource limits, and drift from best practices. It runs fully client-side in your browser, so nothing leaves your machine, making it a fast pre-flight check in local workflows and CI before kubectl apply.
How do I debug a failing readiness or liveness probe?
A failing readiness probe removes the pod from Service endpoints so it gets no traffic, while a failing liveness probe restarts the container and can cause a restart loop. Check kubectl describe pod for probe failure events, then confirm the probe path, port, and command actually succeed inside the container. Often the timeouts or initialDelaySeconds are too aggressive for a slow-starting app, so loosen them or add a startup probe.