image-pull-debug

Diagnose Kubernetes pod image pull failures using pod status, containerd logs, and events.

225|28|Updated Mar 2, 2026
One-click install
npx skills add https://github.com/scitix/siclaw --skill image-pull-debug
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: image-pull-debug
Source: https://github.com/scitix/siclaw/tree/main/skills/core/image-pull-debug
Command: npx skills add https://github.com/scitix/siclaw --skill image-pull-debug

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

This Skill helps diagnose and resolve issues preventing Kubernetes pods from pulling container images, such as ErrImagePull or ImagePullBackOff.

Core Features & Use Cases

  • Root Cause Analysis: Identifies the specific reason for image pull failures by examining pod status, containerd logs, and Kubernetes events.
  • Targeted Troubleshooting: Provides clear, actionable steps based on common error patterns like authentication failures, network issues, or incorrect image references.
  • Use Case: When a new deployment fails because pods are stuck in ImagePullBackOff, this Skill can quickly pinpoint whether the issue is a typo in the image name, a missing imagePullSecret, or a network problem preventing access to the container registry.

Quick Start

Diagnose why my pod 'my-app-pod' in namespace 'default' is failing to pull its image.

Frequently Asked Questions about image-pull-debug

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix ImagePullBackOff errors for my Kubernetes pods?

To fix ImagePullBackOff errors, diagnose the root cause by checking pod status, containerd logs, and Kubernetes events. Common issues include incorrect image references, authentication failures, or network timeouts preventing registry access.

What causes ErrImagePull status in Kubernetes deployments?

ErrImagePull status occurs when Kubernetes cannot fetch the container image. Root causes often involve manifest unknown errors, missing imagePullSecrets, DNS resolution failures, or certificate issues blocking access to the container registry.

How do I troubleshoot container image pull failures on a specific node?

Troubleshoot image pull failures by examining containerd logs on the relevant node alongside Kubernetes events. This identifies specific error patterns like network timeouts or authentication errors to provide targeted resolution steps.

Does this Kubernetes image pull diagnostic tool require write access to modify cluster resources?

No, this diagnostic tool operates strictly within a read-only scope. It analyzes pod status and containerd logs to identify root causes without modifying any Kubernetes resources or cluster configurations.

Why does my pod fail to pull images even when the image name is correct?

Image pull failures with correct names often stem from authentication errors, missing imagePullSecrets, DNS resolution failures, or network timeouts. Examining containerd logs and Kubernetes events pinpoints the exact issue.