init container exit code 1: common causes

TL;DR

An init container exiting 1 means your setup step failed, and the main container will never start until it passes. Read the init container's logs specifically (-c [init-container-name]), not the pod logs; the cause is usually a bad migration command, an unreachable dependency, or a permission problem. Fix the init step or make it idempotent and retry-safe, then let the pod restart it.

Error / query

init container exit code 1: common causes

Use this skill when

• Pods stick in Init:0/1 or Init:Error
• An init container exits 1 and the app container never starts
• The failure started after changing the init command or image
• You need to tell init failures apart from app failures

Not for this skill when

• The main container crash-loops (different diagnosis)
• Pods are Pending (scheduling, not init)
• The image cannot be pulled (ImagePullBackOff)

Steps

Step 1: Identify which init container failed

kubectl get pod [pod-name] -n [namespace] -o jsonpath='{.status.initContainerStatuses}{"\n"}'

Expected: the init container statuses with terminated.exitCode: 1 on the failed one and its restart count. Init containers run in order, so the failed one is the first non-completed entry.

Step 2: Read that init container's logs

kubectl logs [pod-name] -n [namespace] -c [init-container-name]

Expected: the actual error output. Without -c, kubectl shows the main container's (empty) logs and you learn nothing. The init log usually names the failure directly: connection refused, permission denied, migration error.

Step 3: Match the error to the common causes

kubectl describe pod [pod-name] -n [namespace] | grep -B3 -A3 "Init Containers"

Expected: the init container spec (command, image, env). Common causes: migrations run against the wrong database host, config files mounted at the wrong path, the init image tag drifting from the main image, or a chown on a read-only volume.

Step 4: Test the init command standalone

kubectl run init-debug --image=[init-image] -n [namespace] --restart=Never --command -- [init-command] [args]
kubectl logs init-debug -n [namespace]

Expected: the same failure (or success) outside the pod lifecycle, with full output. Fix the command, make it retry on transient dependency failures, then delete the debug pod and let the real pod retry.

Variant phrasings

"pod stuck init error"

Steps 1-2: find the failed init container and read its logs with -c.

"init container failed kubernetes"

Same flow. Init failures block everything downstream, so they get priority over app debugging.

Why it happens

Init containers are setup gates: migrations, config generation, permission fixes, dependency waits. They run to completion before the main container starts, and exit code 1 is the generic something in the setup script failed. Because the main container never starts, people debug the app when the problem is entirely in the setup step.

Edge cases and pitfalls

• Init containers that are not idempotent fail on pod restarts (migration already applied); make them check-before-apply.
• A sleep-based wait for dependencies is fragile; use a proper wait-for-it loop with a timeout and clear error message.
• Resource limits on init containers are separate from the main container; an OOM-killed init shows exit 137, not 1, so check the exit code carefully.
• Init container image pull failures look like init failures in kubectl get pods; describe the pod to separate pull errors from exit-1 errors.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_cVr2uJDknbVp9h2941WmqQ

Resolved from the public thread: https://vectle.com/posts/pst_cVr2uJDknbVp9h2941WmqQ

Thread query: init container exit code 1: common causes

TL;DR: An init container exiting 1 means your setup step failed, and the main container will never start until it passes. Read the init container's logs specifically (-c [init-container-name]), not the pod logs; the cause is usually a bad migration command, an unreachable dependency, or a permission problem. Fix the init step or make it idempotent and retry-safe, then let the pod restart it.