Kubernetes Pod Debugging Guide

Kubernetes pod debugging guide for Pending, CrashLoopBackOff, ImagePullBackOff, logs, events and kubectl describe evidence. Last updated August 31, 2026.

This guide is for the moment when a workload is not serving traffic and the first clue is hidden in pod state, events or container logs. Formalint keeps the page practical: start with observable evidence, keep commands repeatable, avoid pasting secrets into tools and write down the final decision so another developer can reproduce the fix.

The reference baseline for this page is Kubernetes Debug Pods. Vendor documentation defines the exact behavior, while this Formalint guide turns the behavior into a debugging workflow that is easier to follow during incidents, reviews and handoffs.

Fast triage order

Step	Question	Evidence to capture
1	Can you reproduce the issue with the smallest safe sample?	Input, command, URL, version, timestamp and environment name.
2	Is the failure syntax, configuration, transport, permission or runtime behavior?	Error message, status code, log line, stack trace or parser output.
3	Did the same check pass in another environment?	Working version, failing version, config difference and deploy reference.
4	What change would prove the root cause without hiding another issue?	One controlled fix, rollback path and follow-up test.

Useful checks

Confirm the exact tool, runtime, browser, server or database version before comparing behavior.
Reduce the example to a safe sample that keeps the shape of the problem but removes private data.
Prefer one repeatable command over screenshots when you need another person to verify the same behavior.
Record both the failing input and the corrected input so the fix becomes reviewable.

Commands and examples

kubectl get pods -o wide
kubectl describe pod POD_NAME
kubectl logs POD_NAME --previous
kubectl get events --sort-by=.lastTimestamp

Decision checklist

Do not ship the fix until the failing case and at least one normal case both pass.
Check whether the issue belongs in code, configuration, infrastructure, documentation or user input handling.
If the page involves authentication, cookies, tokens, headers, database records or logs, redact values before sharing them.
Update the runbook, test fixture or team note while the details are still fresh.

Common mistakes

The most common mistake is treating the first visible error as the root cause. A timeout can be DNS, TLS, proxy, application, database or client retry behavior. A parser error can be invalid syntax, wrong encoding, invisible whitespace or a sample that no longer matches production. Keep the investigation narrow, but do not skip the boundary where the value crosses from one system into another.

Another mistake is fixing only the happy path. Good debugging leaves behind a small failure example, a working example and a note that explains why the chosen fix is safer than the alternatives considered.

Related Formalint pages

Continue with Docker Compose Debugging, Linux Admin Commands, HTTP Status Codes, API Debugging Checklist.