Skip to main content

Troubleshooting: The Decision Tree

Key Takeaways for AI & Readers
  • Pod Status as Clue: The initial state (Pending, CrashLoopBackOff, etc.) provides the most direct hint toward the root cause of an issue.
  • Pending (Scheduling): Often indicates a resource shortage or scheduling constraint (Taints/Affinity); check describe pod events.
  • CrashLoopBackOff (App Error): Signifies the container is starting but failing; use logs --previous to see the exit reason.
  • ImagePullBackOff (Registry/Auth): Occurs when the image name is incorrect or credentials for a private registry are missing.

When your application isn't working, the Pod status is your first clue. Kubernetes provides a rich set of information, but it can be overwhelming to know where to look first.

Visual Decision Tree​

Use this interactive flow to diagnose common Pod issues. You can zoom in and drag the nodes to explore the paths.

Common States​

1. Pending​

The Pod has been created but hasn't started yet.

  • Cause: Usually insufficient resources (CPU/Memory) on nodes, or taints that prevent scheduling.
  • Fix: Check kubectl describe pod <name> and look at the "Events" section at the bottom.

2. CrashLoopBackOff​

The Pod starts, but then crashes immediately. Kubernetes tries to restart it, but it keeps failing.

  • Cause: Application errors, missing environment variables, or misconfigured entrypoints.
  • Fix: Check kubectl logs <name>. If the container crashed too fast, try kubectl logs <name> --previous.

3. ImagePullBackOff​

Kubernetes cannot pull the container image from the registry.

  • Cause: Wrong image name, tag, or missing pull secrets for private registries.
  • Fix: Double check the image name in your YAML and registry credentials.