Skip to main content
kubectl Commands for Debugging Any Pod

kubectl Commands for Debugging Any Pod

KU
· Founder & Chief Editor
• 7 min read•Updated •63 views

The ordered kubectl toolkit we reach for when a pod misbehaves, with the five commands we run first and what each one actually tells you.

Key takeaways

  • Start every pod investigation with kubectl describe pod and read the Events block, then kubectl logs --previous to see why the last container died, then kubectl get events sorted by lastTimestamp.
  • Use kubectl debug to attach an ephemeral container to shell-less images, and check EndpointSlices when a Service has no backends.

To debug a misbehaving pod, run kubectl describe pod <pod> and read the Events block, then kubectl logs <pod> --previous for the container that crashed, then kubectl get events --sort-by=.lastTimestamp for the namespace story. Those three explain most failures. Use kubectl debug for shell-less images and EndpointSlices for "the Service doesn't route".

Verified against

Kubernetes 1.37 (latest patch 1.37.2, released 2026-10-28), kubectl 1.37, against the kubernetes.io "Debug Running Pods" and "Debug Services" task pages and the kubectl debug reference. Checked October 2026.

Pods break in about four ways: they won't start, they start and crash, they run but can't talk to anything, or they run and eat the node alive. The same handful of kubectl commands covers nearly every one of those cases. This is the toolkit, in the order we actually reach for it. If you want the broader story on reading Kubernetes failures, our Kubernetes troubleshooting guide goes wider. This post stays close to the terminal; for everyday commands outside debugging, keep our kubectl cheat sheet open.

The five we run first

Before any theory, here are the five commands that resolve most pod problems before the coffee is finished:

Bash
$ kubectl get pods -o wide
$ kubectl describe pod <pod>
$ kubectl logs <pod> --previous
$ kubectl get events --sort-by=.lastTimestamp
$ kubectl top pod <pod>

get pods -o wide adds the node name and pod IP to the usual output. Knowing which node a pod landed on matters because a surprising share of "random" failures are one bad node. Everything after this is drilling into whichever of those five pointed at something odd.

Scenario: it won't start

Pending, ContainerCreating, ImagePullBackOff, Init:0/1. The pod exists but never gets to Running.

Start with describe. The Events block at the bottom is where the real message lives:

Bash
$ kubectl describe pod <pod>

Failed scheduling usually means no node has the CPU or memory you asked for, or a taint or node selector nobody can satisfy. ImagePullBackOff means a wrong tag, a private registry with no pull secret, or a typo in the image name. For init containers stuck at Init:0/1, read that specific container:

Bash
$ kubectl logs <pod> -c <init-container-name>

If describe isn't enough, widen out to the namespace and let the events tell the story in order:

Bash
$ kubectl get events --sort-by=.lastTimestamp

Sort matters. The default ordering is close to useless; --sort-by=.lastTimestamp puts the freshest failure at the bottom where you're already looking. When a pod is Pending because of resources, confirm what's actually free:

Bash
$ kubectl top node

Scenario: it starts and crashes

CrashLoopBackOff, or a Running pod that keeps restarting. The restart count in get pods is your tell.

The container that crashed is already gone, so live logs show you the new attempt, not the death. Ask for the previous one:

Bash
$ kubectl logs <pod> --previous
$ kubectl logs <pod> -c <container> --previous

--previous is the single most underused flag in kubectl. It pulls logs from the last terminated container, which is exactly the one that failed. For a multi-container pod, -c picks the container. To watch a fresh restart live:

Bash
$ kubectl logs -f <pod>

describe still earns its place here too. The Last State and Reason fields tell you if the kernel OOM-killed the process (Reason: OOMKilled) versus the app exiting on its own (a plain nonzero exit code). Those two point at completely different fixes: one is a limits problem, the other is a code or config problem. Our Kubernetes exit codes decoded table maps the common numbers (137, 143, 1) to causes.

When logs are ambiguous, get inside a running instance and poke around:

Bash
$ kubectl exec -it <pod> -- /bin/sh

Some hardened images ship no shell at all. That's where ephemeral containers come in:

Bash
$ kubectl debug -it <pod> --image=busybox:1.28 --target=<container>

This attaches a throwaway ephemeral container. The --target flag puts it in the target container's process namespace, which the docs note is necessary when the pod doesn't share process namespaces already, so you get a shell and tools without rebuilding the image. For a node-level problem, the same command debugs the host:

Bash
$ kubectl debug node/<node> -it --image=ubuntu

Scenario: it runs but networking is broken

The pod is healthy, and something still can't reach it. This is where people burn hours.

Check whether the Service actually has backends. The upstream "Debug Services" page checks EndpointSlices, not the legacy Endpoints object:

Bash
$ kubectl get endpointslices -l kubernetes.io/service-name=<service>

No slices, or slices with no addresses, means the Service selector doesn't match your pod labels. No amount of DNS debugging fixes a selector typo, so rule it out first. Then test the pod directly, bypassing the Service:

Bash
$ kubectl port-forward <pod> 8080:80

Now localhost:8080 hits the pod. If that works but the Service doesn't, the problem is the Service or ingress, not the app. If you need a file off the pod to inspect a config that got mounted wrong:

Bash
$ kubectl cp <pod>:/etc/app/config.yaml ./config.yaml

Scenario: it's eating resources

Slow, throttled, or getting killed under load.

Bash
$ kubectl top pod <pod>
$ kubectl top pod --sort-by=memory

top needs metrics-server installed, so install it on day one. Compare live usage against the limits set on the pod:

Bash
$ kubectl get pod <pod> -o yaml

The full YAML shows requests, limits, volume mounts, env vars, and the live status conditions. It's verbose, so pull just what you need with jsonpath:

Bash
$ kubectl get pod <pod> -o jsonpath='{.spec.containers[*].resources}'

jsonpath is worth ten minutes of learning. It turns "scroll through YAML" into "answer one question." If you forget a field's shape, ask the API:

Bash
$ kubectl explain pod.spec.containers.resources

When the deploy itself is the problem

Sometimes the pod is fine and the rollout is wrong. Watch it land:

Bash
$ kubectl rollout status deployment/<name>

If a bad image shipped and pods are crashing, roll back before you debug further:

Bash
$ kubectl rollout undo deployment/<name>

Get the cluster stable, then investigate the broken revision at your own pace.

Questions people ask

How do I see logs from a crashed pod in Kubernetes?

Run kubectl logs <pod> --previous, adding -c <container> for multi-container pods. A crashed container has already been replaced, so plain kubectl logs shows the new attempt, which is often empty or healthy-looking. --previous returns the output of the last terminated instance, the one that actually failed. Pair it with kubectl describe pod to see Last State, Reason, and the exit code.

How do I debug a pod that has no shell?

Use an ephemeral container: kubectl debug -it <pod> --image=busybox:1.28 --target=<container>. It adds a temporary container with its own tools to the running pod and, with --target, joins the target container's process namespace so you can inspect its processes. The image you are debugging stays untouched, and nothing needs rebuilding. The docs note an ephemeral container cannot be changed or removed once added, so recreate the pod when finished if that matters.

Why does my Kubernetes Service have no endpoints?

Almost always because the Service selector does not match the pod labels, or the matching pods are not Ready. Run kubectl get endpointslices -l kubernetes.io/service-name=<service> and kubectl get pods --show-labels, then compare. Pods failing their readiness probe show up as not ready in the slice and receive no traffic, so a crash-looping or still-starting backend can look a lot like a selector typo from the client side.

The call we'd make

Reach for describe and --previous logs before anything fancier. Between those two and get events --sort-by, you've explained most pod failures without ever opening a dashboard. Save kubectl debug for the shell-less images and node problems, and lean on jsonpath so you're asking one question at a time instead of squinting at a wall of YAML. The tooling around Kubernetes keeps growing, but the pod that's down at 2am still answers to these same commands.

Sources

Explore topics:KubernetesDevOps
React
Share this post
Cite this article
Plain text

Kiril Urbonas (2026). kubectl Commands for Debugging Any Pod. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/kubectl-debugging-commands

Markdown

[kubectl Commands for Debugging Any Pod](https://www.devopsness.com/blog/kubectl-debugging-commands) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)

KU

Kiril Urbonas

Founder & Chief Editor

586 articles
View all articles by Kiril Urbonas

You might have missed

Evergreen posts worth revisiting.