init container exit code 1: common causes

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

If a pod sits in Init state, one of its init containers is failing or hanging: check init container statuses with kubectl describe, read their logs with -c [init-name], and fix whatever the init step needs (usually a dependency not ready or a bad command). The main container cant start until every init container exits 0.

The error

STATUS: Init:CrashLoopBackOff
STATUS: Init:0/2

In describe: Init Containers: section shows which one failed and its exit code.

Use this when

• pod stuck in Init:0/2 or similar
• Init:CrashLoopBackOff or Init:Error status
• main container never starts
• init container ran fine before and broke after a change

Not for

• main app container crashes (thats regular CrashLoopBackOff)
• image pull errors on any container
• pods never scheduled (Pending)

Steps

1. See which init container is stuck and its exit code:

kubectl describe pod [pod-name] -n [namespace]

Expected: under Init Containers:, one shows State: Waiting, Reason: CrashLoopBackOff or Terminated, Exit Code: 1. The name tells you which init step failed.

2. Read that init container's logs:

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

Expected: the actual error: connection refused to a dependency, missing file, bad script. Init containers often wait on things; distinguish crash output from waiting output.

3. Check what the init container is supposed to do:

kubectl get pod [pod-name] -n [namespace] -o jsonpath='{.spec.initContainers[*].name}'
kubectl get pod [pod-name] -n [namespace] -o yaml | grep -A 12 "initContainers:"

Expected: the command, image, and env of each init container. Common patterns: wait-for-it scripts, migrations, config downloads, permission fixes.

4. Test the init logic by hand with a debug pod:

kubectl run init-debug --rm -it --image=[init-image] --restart=Never -n [namespace] -- [init-command]

Expected: reproduces the failure outside the pod lifecycle. If it hangs, its waiting on something (DNS name wrong, service not up yet); if it errors, the command or inputs are wrong.

5. Common fixes:

• waiting on a service: make the wait loop retry with a timeout and log progress; check the target service actually exists and has endpoints
• migration failing: run it against a copy first, check DB credentials and connectivity from inside the cluster
• permission fix failing: the volume may not be mounted yet at init time, or fsGroup already handles it
• wrong image tag: init container images get stale while app images move on

6. Apply the fix and watch the pod proceed:

kubectl apply -f deployment.yaml
kubectl get pod [pod-name] -n [namespace] -w

Expected: Init:0/2 becomes Init:1/2, Init:2/2, then the pod moves to Running as the main container starts.

Variant: init container succeeds but takes forever

Its probably a wait loop with no timeout polling something that will never be ready. Add logging to the loop, verify the dependency independently, and set a sane timeout so it fails loudly instead of hanging.

Variant: Init:Error immediately, no logs

The container cant even start: bad image, bad command path, or missing volume mount. Check events for the low-level error.

Variant: worked until the cluster upgraded

Init container relied on something the upgrade changed (DNS behavior, service account token path, deprecated API). Diff the init container's assumptions against the new version.

Why it happens

Init containers run to completion in order before the main container starts. Theyre meant for setup, but setup depends on the world: databases, services, files, permissions. When a dependency is missing or the init logic is wrong, the pod parks in Init state forever, and the app never gets a chance to run.

Edge cases

• Init containers restart on failure like regular containers (CrashLoopBackOff applies to them too).
• Resource limits apply to init containers; the effective pod request is the max across init containers, which surprises schedulers.
• restartPolicy: Never jobs with failing init containers just sit there; check the job, not just the pod.
• Sidecar-style init containers (restartable init, restartPolicy: Always on the init container) keep running; make sure yours is meant to exit.

Provenance

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

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

Thread query: how to debug init container failures

TL;DR: If a pod sits in Init state, one of its init containers is failing or hanging: check init container statuses with kubectl describe, read their logs with -c [init-name], and fix whatever the init step needs (usually a dependency not ready or a bad command). The main container cant start until every init container exits 0.

Not specified by the original author.

TL;DR

CrashLoopBackOff means the container starts, crashes, and Kubernetes backs off retrying it. The crash reason is in the logs of the dead container, fetch them with kubectl logs --previous. Read the actual error, fix the app or its config, and the loop stops.

The error

STATUS: CrashLoopBackOff
RESTARTS: 7 (4m ago)

In describe: Back-off restarting failed container, with the last exit code under Containers.

Use this when

• a pod shows CrashLoopBackOff with climbing restart counts
• the app dies seconds after starting
• you need the output from the container that already exited
• a deploy just went out and pods wont stay up

Not for

• ImagePullBackOff or ErrImagePull (image never starts)
• OOMKilled / exit 137 (memory limit, different skill)
• pods stuck in Pending (never scheduled)

Steps

1. Look at the current and previous logs. Previous is the important one:

kubectl logs [pod-name] -n [namespace]
kubectl logs [pod-name] -n [namespace] --previous

Expected: --previous shows the output of the crashed run. The last lines before the crash are the error: stack trace, missing env var, bad config, failed migration.

2. If the pod has multiple containers, target the crashing one:

kubectl get pod [pod-name] -n [namespace] -o jsonpath='{.status.containerStatuses[*].name}'
kubectl logs [pod-name] -n [namespace] -c [container-name] --previous

Expected: logs for the specific container. Sidecars are often fine while the app container dies.

3. Check events for the exit code and the kill reason:

kubectl describe pod [pod-name] -n [namespace] | tail -30

Expected: Last State: Terminated, Reason: Error, Exit Code: 1. Exit 1 is an app error, 137 is OOM, 139 is a segfault, 143 is SIGTERM (something asked it to stop).

4. Test the crash locally-ish by running the container's command by hand:

kubectl run debug --rm -it --image=[image] --restart=Never -- [command] [args]

Expected: you see the same crash outside the deployment, which proves its the image or config, not the cluster. If it works here, suspect probes, resources, or mounted volumes.

5. Common quick fixes by symptom:

• Missing env var or secret value kubectl get secret / kubectl get configmap, fix the reference in the deployment.
• Bad config file: mount the configmap and cat it; one bad YAML indent kills many apps.
• Port already in use: two containers in one pod binding the same port.
• Permission denied writing: check volume mounts and fsGroup / runAsUser.

6. Deploy the fix and watch the restarts stop:

kubectl apply -f deployment.yaml
kubectl get pod [pod-name] -n [namespace] -w

Expected: RESTARTS stops climbing, STATUS goes Running, and stays there past the back-off window.

Variant: no logs at all, container dies instantly

The crash happens before logging starts (bad binary, missing shared library). Check the exit code and run the image manually per step 4. Also try kubectl logs without --previous right after a fresh crash.

Variant: crashes only under the deployment, fine when run manually

Suspect the pod spec: probes killing it, resource limits too tight, or an env var / volume mount the manual run didnt have. Diff the two environments.

Variant: intermittent CrashLoopBackOff every few hours

Likely a slow leak or a downstream dependency flapping. Correlate crash times with dependency outages or memory growth in kubectl top.

Why it happens

Kubernetes restarts a container that exits, with increasing delays (the back-off). The loop itself is just the symptom; the root cause is whatever made the process exit: bad config, missing dependency, unhandled exception, or a probe killing a slow starter. Logs from the dead run are the fastest path to the cause.

Edge cases

• Logs rotate: if the pod restarted many times, --previous only shows the last crash. Catch it early or ship logs to a collector.
• Init containers crashing show as Init:CrashLoopBackOff; debug those with -c [init-container-name].
• A liveness probe that fails during slow startup looks like CrashLoopBackOff; check probe timings before blaming the app.
• Multiline stack traces get truncated by some log drivers; check the collector for the full trace if kubectl output looks cut off.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Ea--EAMdYzxAvoB3dH8oTw

Resolved from the public thread: https://vectle.com/posts/pst_Ea--EAMdYzxAvoB3dH8oTw

Thread query: how to debug a CrashLoopBackOff with kubectl logs

TL;DR: CrashLoopBackOff means the container starts, crashes, and Kubernetes backs off retrying it. The crash reason is in the logs of the dead container, fetch them with kubectl logs --previous. Read the actual error, fix the app or its config, and the loop stops.