A Kubernetes Pod Is Failing: A Beginner’s Investigation Checklist

When a Kubernetes application fails, begin by identifying where the failure happens. Scheduling, downloading an image, starting a process, and passing a readiness check are different stages. Repeatedly deleting the Pod can remove evidence without addressing the cause.

This guide is a diagnostic checklist for a training environment where you have permission to inspect workloads. It is based on the Kubernetes Pod debugging documentation.

Confirm the cluster and namespace

Before running commands, check that your context points to the intended cluster. Use explicit namespaces so you do not investigate a different copy of the application.

kubectl config current-context
kubectl get pods -n lab
kubectl describe pod POD_NAME -n lab

Replace POD_NAME with the name shown in your own lab. Do not paste the placeholder unchanged. Record the container state, restart count, and recent events. The STATUS column is a helpful summary, but it is not a complete diagnosis.

If the Pod cannot be scheduled

As the Pod lifecycle documentation explains, a Pending Pod may be waiting for scheduling or another prerequisite. Read the events before changing resource requests. Look for a specific constraint: insufficient capacity, an unsatisfied placement rule, or an unavailable storage claim.

Compare the workload’s requirements with the cluster you actually have. A manifest copied from a larger cluster can request resources your learning environment cannot provide. Record the mismatch and choose a deliberate adjustment rather than removing every constraint.

If the image cannot be pulled

For image-pull errors, inspect the full image reference, registry access, and pull credentials. Check whether the referenced image and tag exist. A spelling error and a permission error need different fixes.

An image that runs on your laptop may still be unavailable to a remote node. Confirm that you published it to a registry the cluster can reach. Do not place a registry password into a public manifest to make the error disappear.

If the process starts and crashes

Inspect the relevant container’s logs. In a multi-container Pod, identify the container explicitly. If it restarted, the previous instance’s logs may contain the useful error.

kubectl logs POD_NAME -n lab -c CONTAINER_NAME
kubectl logs POD_NAME -n lab -c CONTAINER_NAME --previous

Treat logs as evidence. Compare the startup command and required configuration with the image’s expectations. A restart loop describes repeated failure; it does not identify the application bug or configuration mistake by itself.

If it runs but is not ready

Check the readiness probe and the application’s actual listening port and path. Then examine the Service’s selectors and endpoints. A process can be running while the service has no ready backend.

Use a request that represents the behaviour you need to verify. A health endpoint returning success is useful, but a separate database-dependent operation may still fail. Be precise about what your check proves.

Change one thing and verify

Write down your hypothesis, the supporting observation, and the smallest change that would test it. After applying the change in your lab, check the workload and application again. Record both successful and unsuccessful attempts.

Turn the final explanation into a runbook. Include the symptom, checks, resolution, and verification. Continue with the Kubernetes learning guide to connect Pods, Deployments, and Services.