CrashLoopBackOff and ImagePullBackOff — the image and startup failures

CrashLoopBackOff is the container crashing after start. ImagePullBackOff is the kubelet failing to pull the image. The previous logs and the events are the diagnostic. The discipline is the same 11-step methodology: read the events, read the previous logs, identify the cause, apply the remediation.

CrashLoopBackOff

A CrashLoopBackOff is the kubelet’s response to a container that exits repeatedly. The kubelet applies an exponential backoff between restarts (10s, 20s, 40s, 80s, … up to 5 minutes) to avoid hot-looping the container.

flowchart TD
    A[Container starts] --> B[Exits with non-zero]
    B --> C[Backoff: 10s]
    C --> D[Restart]
    D --> E[Exits again]
    E --> F[Backoff: 20s]
    F --> G[Restart]
    G --> H[Exits again]
    H --> I[Backoff: 40s]
    I --> J[CrashLoopBackOff]

A real kubectl describe pod for a CrashLoopBackOff:

Name:         billing-7d8f-abcde
Namespace:    prod
Status:       Running
IP:           10.244.5.23
Controlled By:  Deployment/billing
Containers:
  billing:
    Container ID:   containerd://abc123...
    Image:          registry.example.com/billing:1.2.3
    Image ID:       registry.example.com/billing:1.2.3@sha256:def456...
    Port:           8080/TCP
    Host Port:      0/TCP
    State:          Waiting
      Reason:       CrashLoopBackOff
    Last State:     Terminated
      Reason:       Error
      Exit Code:    1
      Started:      Fri, 16 Aug 2026 04:23:01 +0000
      Finished:     Fri, 16 Aug 2026 04:23:04 +0000
    Ready:          False
    Restart Count:  12
    Limits:
      cpu:     500m
      memory:  512Mi
    Requests:
      cpu:     250m
      memory:  256Mi
Conditions:
  Type           Status
  Initialized    True
  Ready          False
  ContainersReady  False
  PodScheduled   True
Events:
  Type     Reason          Age   From               Message
  ----     ------          ----  ----               -------
  Normal   Pulling         24m   kubelet            Pulling image "registry.example.com/billing:1.2.3"
  Normal   Pulled          24m   kubelet            Successfully pulled image "registry.example.com/billing:1.2.3"
  Normal   Created         24m   kubelet            Created container billing
  Normal   Started         24m   kubelet            Started container billing
  Warning  BackOff         12m   kubelet            Back-off restarting failed container billing

The events tell the operator:

• The image was pulled successfully.
• The container was created and started.
• The container is failing immediately after start.
• The kubelet is applying a backoff.

The remediation is in the previous logs.

kubectl logs -n prod billing-7d8f-abcde -c billing --previous

The previous logs show the application’s crash:

Traceback (most recent call last):
  File "/app/billing.py", line 12, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

The application is crashing because the new image is missing a library. The remediation is to fix the image (or rollback).

ImagePullBackOff

An ImagePullBackOff is the kubelet’s response to an image that cannot be pulled. The kubelet applies the same exponential backoff.

A real kubectl describe pod for an ImagePullBackOff:

Containers:
  billing:
    Image:      registry.example.com/billing:1.2.3
    State:      Waiting
      Reason:   ImagePullBackOff
    Ready:      False
Events:
  Type     Reason          Age   From               Message
  ----     ------          ----  ----               -------
  Normal   Pulling         8m    kubelet            Pulling image "registry.example.com/billing:1.2.3"
  Warning  Failed          8m    kubelet            Failed to pull image "registry.example.com/billing:1.2.3": rpc error: code = Unknown desc = Error response from daemon: pull access denied for registry.example.com/billing, repository does not exist or may require 'docker login'
  Warning  Failed          6m    kubelet            Error: ErrImagePull
  Normal   BackOff         5m    kubelet            Back-off pulling image "registry.example.com/billing:1.2.3"

The events tell the operator:

• The image is failing to pull.
• The reason is pull access denied — the kubelet’s credentials are not authorised for the registry.

The remediation is to fix the imagePullSecrets, the registry credentials, or the image name.

Common causes

The most common causes of CrashLoopBackOff:

• Missing library. The image is missing a Python library, a Node module, a Go binary.
• Bad configuration. The application is reading a ConfigMap that has a wrong value.
• Bad startup. The application’s startup is failing (e.g., the database is unreachable).
• Liveness probe failure. The liveness probe is killing the container (see Part CXIX-04).

The most common causes of ImagePullBackOff:

• Wrong image name. The image name is wrong (typo, wrong registry).
• Wrong tag. The image tag does not exist.
• Missing credentials. The imagePullSecrets are missing or wrong.
• Network. The kubelet cannot reach the registry.

Production discipline

A CrashLoopBackOff is the workload’s view of the failure. The previous logs are the diagnostic. The discipline is to read the events, read the previous logs, identify the cause, and apply the remediation.

• Distinguish CrashLoopBackOff from ImagePullBackOff. The events tell the operator which one.
• Fix the image, not the workload. The Pod’s spec is correct; the image is wrong.
• Rollback, then fix. The restore is the rollback; the fix is the follow-up.

Quiz