阅读中文版本

Kubernetes Init:Error / Init:CrashLoopBackOff — Init Container Fails

Fix init container failures by reading its logs, checking its dependencies and commands, and verifying it exits zero before main containers start.

kubectl logs <pod> -c <init-container>

kubectl get pod <pod> -o jsonpath="{.status.initContainerStatuses[*].state}"

Symptoms

When you hit “Kubernetes Init:Error / Init:CrashLoopBackOff — Init Container Fails”, guessing wastes time. The guide below follows evidence: reproduce the symptom, run targeted diagnostics, identify the root cause, apply the fix, and verify it with concrete checks.

Observed symptoms include:

• Pod status shows Init:Error or Init:CrashLoopBackOff
• Main containers never start
• A migration or setup init container exits non-zero

Reproduce and Diagnose

Reproduce the failure in isolation before changing any code. Work through the checks below in order; each one narrows the search space.

Step 1: Read the init container logs

kubectl logs <pod> -c <init-container>

Init container logs show its failure output, which main-container logs would not.

Step 2: Inspect its exit code and command

kubectl get pod <pod> -o jsonpath="{.status.initContainerStatuses[*].state}"

A non-zero exit and the terminated reason pinpoint what to fix in the command or dependency.

Likely contributors, in order of frequency:

• The init container command fails (bad path, missing binary, wrong args)
• A dependency such as a database is not yet reachable
• A migration errors or the container runs as the wrong user

Root Cause

Init containers run sequentially and must each exit zero before any main container starts. A failure blocks the pod with Init:Error or Init:CrashLoopBackOff, so main application logs never appear.

The Fix

Fix the init command, add retry logic for dependencies that may not be ready, run migrations with the right user and error handling, and keep init containers idempotent and fast.

Watch out: Long or blocking init containers delay every restart; keep them short and avoid infinite waits without timeout.

spec:
  initContainers:
    - name: wait-for-db
      image: postgres:16
      command:
        - sh
        - -c
        - |
          until pg_isready -h db -p 5432; do echo waiting; sleep 2; done
      # bounded retry instead of infinite wait
      # timeout: use a loop counter or a short backoff budget
  containers:
    - name: app
      image: myrepo/app:1.0.0

Verify and Prevent

Rerun the pod and confirm init containers complete with exit 0 and the main container starts; verify logs show the fix took effect.

Once verified, add a regression test that reproduces the original symptom so the failure cannot silently return.

This class of failure is usually environmental rather than pure logic, so capture the exact command, the environment variables, and the working directory in your bug report. Reproduce it in the smallest possible script, then widen the scope only once the minimal case is understood. A short written checklist for this failure mode saves hours the next time it appears.