iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
When a Kubernetes Pod is Pending, restarting, or running without serving traffic, start with its namespace, status, and events—not a configuration change. Then inspect the affected container’s current or previous logs and follow the branch that matches the evidence. If the Pod itself looks healthy, check the Service or cluster layer instead.
Start with the right Pod, namespace, and container
First establish the scope of the problem. Identify the namespace, the workload that owns the Pod, the affected Pod, and—if it has more than one—the container showing the symptom. If a workload has multiple replicas, compare a failing Pod with a healthy one. A problem isolated to one replica suggests a different path from one affecting every replica.
kubectl get pods -n <namespace>
kubectl describe pod <pod> -n <namespace>
kubectl get events -n <namespace>Use the actual namespace in each command. Events are scoped to a namespace, so querying a different one can hide the relevant message. The kubectl command reference covers inspection of Pods and workload resources.
Inspect status and events before changing anything
kubectl describe pod shows Pod details, container states, restart counts, conditions, and recent events. Read these together: the status points to what is happening, while an event can explain why. For example, a FailedScheduling event may identify a scheduling constraint such as insufficient resources. Treat the event text as evidence for this Pod, not as proof that every Pending Pod has the same cause.
#1 Best Overall
The Kubernetes Pod debugging guide describes how to inspect a Pod that remains Pending and how to read its events.
My pod stays pending
A Pending Pod has not reached the point where ordinary application logs can explain a startup failure. Begin with the scheduling-related events from kubectl describe pod <pod> -n <namespace>. Use the message to investigate the specific resource, placement, or other scheduling clue it reports before editing a manifest.
If the event does not make the cause clear, compare the affected Pod with other replicas and inspect the owning workload’s configuration and status. Avoid assuming a resource shortage unless the event or other evidence supports it.
Why is my Pod restarting?
For CrashLoopBackOff or another repeated restart, inspect the affected container’s logs and state. When a container has restarted, --previous retrieves output from its preceding instance:
kubectl logs <pod> -c <container> -n <namespace>
kubectl logs <pod> -c <container> --previous -n <namespace>Check the container’s exit details and startup configuration alongside the logs. If the Pod has multiple containers, specify the one that is failing; output from another container may not explain the restart.
For a Pod that is stuck before the application container starts, inspect init-container status and logs by the init container’s name. Kubernetes maintains a separate guide to troubleshooting init containers.
Debug Running Pods
If a Pod is Running but not Ready or not serving requests, examine its logs and probe configuration, then test the application and its dependencies from a context appropriate to the failure. A Running state alone does not establish that the application is ready or reachable by clients.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsChoose the inspection method based on the container’s state and contents:
| Method | Useful when | Limits and considerations |
|---|---|---|
kubectl logs |
You need a container’s output, including output from a previous crashed instance with --previous. |
Specify the container when the Pod has more than one. Logs are not a substitute for retained, centralized logging. |
kubectl exec |
The target container is running and contains the shell or troubleshooting command you need. | Minimal or distroless images may not include a shell or diagnostic utilities. |
| Ephemeral debug container | You need temporary inspection in the context of a running Pod, especially when exec is insufficient. |
Choose an appropriate image and security profile. Ephemeral containers are not automatically restarted and cannot be changed or removed after they are added. |
| Debug copy of a Pod | You need a modified copy to investigate a workload without relying on the original container image’s tools. | Behavior depends on the selected debug options and cluster policy; remove the copied debug Pod when finished. |
| Node debug Pod | Evidence points to a node-level problem rather than an application container. | Node diagnosis can require identifying the node and access appropriate to the environment. |
Use kubectl exec only when the target is running and has the required tool. For example, an interactive shell attempt is:
kubectl exec -it <pod> -c <container> -n <namespace> -- shIf the container has crashed or its image lacks debugging utilities, Kubernetes documents ephemeral containers for interactive troubleshooting. Ephemeral containers have been stable since Kubernetes v1.25. They are user-initiated, temporary inspection containers; they are not automatically restarted and cannot be modified or removed once added. Whether a targeted process namespace is visible can depend on container-runtime support.
Use kubectl debug deliberately
kubectl debug can add an ephemeral container to a running Pod, create a modified copy of a Pod, or create a Pod for node debugging. A simple starting form for an ephemeral container is:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →kubectl debug -it <pod> -n <namespace> --image=busyboxThe exact options depend on the target and task. Check the installed kubectl version, cluster support, and security policy; the kubectl debug reference documents the available forms and flags.
Best Value
Debug profiles include general, baseline, restricted, netadmin, and sysadmin. Choose the least permissive profile that supports the investigation. The reference warns that profile capabilities may not work when the target Pod is configured to run as non-root; sysadmin can grant privileged capabilities, so it is not a routine default. A debug container runs in the Pod context, so its image and access should be chosen with the cluster’s security requirements in mind.
When the Pod looks healthy but access still fails
If the application responds within its Pod but clients cannot reach it, move to the Service path. Check whether the Service selects the intended Pods, whether its endpoints reflect those Pods, and whether connectivity works from an appropriate in-cluster context. Kubernetes has a separate Service debugging guide.
If the evidence points beyond the application and Service—for example, to a node or broader cluster condition—use the cluster-level path in Kubernetes’ troubleshooting documentation. Advanced Pod investigation can require identifying the node and obtaining suitable shell access.
Recommended Free Tools
Plan for logs beyond the live Pod
kubectl logs is useful for current output and, after a restart, a previous container instance. Kubernetes does not provide native storage for logs; keeping and centralizing them requires a separate logging solution. The Kubernetes logging architecture documentation explains this distinction.
Check guidance for your Kubernetes release
Debugging behavior and available options can depend on the Kubernetes version, kubectl version, container runtime, managed-cluster environment, and security policy. Verify commands against your installed versions and consult the documentation’s known issues and troubleshooting guidance when symptoms do not fit the expected path.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
