Kubernetes Pod Doctor
Find out why your pod is broken without leaving VS Code. Pod Doctor turns
CrashLoopBackOff, ImagePullBackOff, OOMKilled and other failures into a
plain-English cause and concrete steps to fix it, often with a ready-to-run
kubectl command.
No AI, no API key, no account. Your cluster data stays on your machine.
Why use it
Most pod failures never write an application log line, so kubectl logs comes
back empty and you end up piecing together describe, events and exit codes.
Pod Doctor reads pod status, events and logs together and tells you what
they add up to.
Get started
Install Kubernetes Pod Doctor from the Extensions view, or run:
code --install-extension manmohanmirkar123.k8s-pod-doctor
Make sure kubectl can reach your cluster. Pod Doctor uses the same
kubeconfig, so there is nothing else to set up.
Check the status bar: it shows Pods OK or the number of unhealthy pods.
Click it to open the failure report.
What it diagnoses
| Failure |
What Pod Doctor tells you |
| CrashLoopBackOff |
The crashed container's previous logs and what its exit code means, including liveness and startup probe restarts |
| ImagePullBackOff / ErrImagePull |
Whether it's authentication, a missing tag or an unreachable registry |
| OOMKilled |
The container's memory limit and how to address it |
| Pending / Unschedulable |
The scheduler's reason: insufficient CPU or memory, taints, node selectors or volumes |
| CreateContainerConfigError |
The Secret or ConfigMap that's missing |
| RunContainerError |
A bad command or entrypoint |
| Volume mount failures |
Why a pod is stuck before its containers start |
| Readiness probe failures |
Why a running container never becomes ready |
| Security context violations |
Which policy setting stopped the container from starting |
| Evicted / DeadlineExceeded |
Why Kubernetes removed or stopped the pod |
| Pod network (CNI) sandbox errors |
Why the pod's network couldn't be set up |
| Node problems |
When the node, rather than the pod, is at fault |
Init containers are covered too. Every diagnosis includes a confidence level, so
you can tell firm evidence from a best guess.
Using it
- Status bar: see pod health at a glance and click to open the report.
- Failure report: every unhealthy pod in one page, with its root cause and
suggested fixes.
- Pod Doctor sidebar: browse unhealthy pods and click one to open its
diagnosis.
- Context and namespace pickers: switch clusters or namespaces, or scan all
namespaces, from the sidebar toolbar or the report.
Pods are scanned when VS Code starts and whenever you refresh or open the
report. Results don't update automatically in between, so use Refresh to
see the latest state.
Commands are available in the Command Palette under Pod Doctor.
Privacy and safety
- Read-only: Pod Doctor never creates, changes or deletes anything in your
cluster.
- Nothing leaves your machine: the only network traffic is to your own
cluster's API server.
- No stored credentials: it uses your existing kubeconfig.
- Automatic startup scan: when VS Code starts, Pod Doctor lists pods and
events in your selected context, or your kubeconfig's current context if you
haven't picked one. Logs are read only when you open the report, and only the
last 50 lines from crashed or failed containers.
Your Kubernetes user needs permission to list pods and events and read pod logs.
Listing namespaces is optional: without it, you can type a namespace name.
Feedback
Found a failure it misses or explains badly?
Open an issue,
ideally with the pod's status and events.
Contributing
See ARCHITECTURE.md
for build, test and local cluster instructions.
License
MIT
