---
title: "debug pod"
description: "Debug a failing or unhealthy Kubernetes pod by analyzing events, logs, and configuration."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/debug-pod
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:19:36.460Z
license: CC-BY-4.0
attribution: "debug pod — Claudary (https://claudary.paisolsolutions.com/skills/debug-pod)"
---

# debug pod
Debug a failing or unhealthy Kubernetes pod by analyzing events, logs, and configuration.

## Overview

Debug a failing or unhealthy Kubernetes pod by analyzing events, logs, and configuration.

## Steps

1. Get pod status: `kubectl get pod <name> -n <namespace> -o wide`.
2. Describe the pod for events and conditions: `kubectl describe pod <name> -n <namespace>`.
3. Analyze the pod state:
   - **Pending**: Check node resources, scheduling constraints, PVC binding.
   - **CrashLoopBackOff**: Check container logs for startup errors.
   - **ImagePullBackOff**: Verify image name, tag, and registry credentials.
   - **OOMKilled**: Check memory limits vs actual usage.
   - **Running but unhealthy**: Check probe configuration and endpoints.
4. Fetch container logs: `kubectl logs <pod> -n <ns> --previous` for crash logs.
5. Check resource usage: `kubectl top pod <name> -n <namespace>`.
6. Verify configuration:
   - ConfigMaps and Secrets are mounted correctly.
   - Environment variables are set.
   - Service account has required permissions.
7. Suggest fixes based on the diagnosis.

## Format

```
Pod: <name> in <namespace>
Status: <status>
Restarts: <count>
Node: <node-name>

Diagnosis:
  Root cause: <description>
  Evidence: <log lines or events>

Fix:
  1. <action to take>
  2. <verification command>
```

## Rules

- Always check events first; they often reveal the root cause immediately.
- Fetch logs from the previous container instance for crash analysis.
- Check node-level issues if multiple pods on the same node are affected.
- Verify DNS resolution if the pod cannot reach other services.
- Check RBAC permissions if the pod gets authorization errors.

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/debug-pod) · https://claudary.paisolsolutions.com