kubernetes/kubernetes · error

CrashLoopBackOff

Error message

CrashLoopBackOff

What it means

ErrCrashLoopBackOff (sync_result.go:77) is a sentinel error used in SyncResult.Error to signal that a container has terminated and the kubelet is applying exponential backoff before the next restart attempt. It is not a thrown error in the panic sense; it is attached to a SyncResult.Fail() call to drive the CrashLoopBackOff status and backoff scheduling (MinBackoffExpiration).

Source

Thrown at pkg/kubelet/container/sync_result.go:77

				if !found || backoff.Before(min) {
					min = backoff
					found = true
				}
			}
		}
		return min, found
	default:
		if e := errors.Unwrap(err); e != nil {
			return MinBackoffExpiration(e)
		}
		return time.Time{}, false
	}
}

// TODO(random-liu): We need to better organize runtime errors for introspection.

// ErrCrashLoopBackOff returned when a container Terminated and Kubelet is backing off the restart.
var ErrCrashLoopBackOff = errors.New("CrashLoopBackOff")

var (
	// ErrContainerNotFound returned when a container in the given pod with the
	// given container name was not found, amongst those managed by the kubelet.
	ErrContainerNotFound = errors.New("no matching container")
)

var (
	// ErrRunContainer returned when runtime failed to start any of pod's container.
	ErrRunContainer = errors.New("RunContainerError")
	// ErrKillContainer returned when runtime failed to kill any of pod's containers.
	ErrKillContainer = errors.New("KillContainerError")
	// ErrCreatePodSandbox returned when runtime failed to create a sandbox for pod.
	ErrCreatePodSandbox = errors.New("CreatePodSandboxError")
	// ErrConfigPodSandbox returned when runetime failed to get pod sandbox config from pod.
	ErrConfigPodSandbox = errors.New("ConfigPodSandboxError")
	// ErrKillPodSandbox returned when runtime failed to stop pod's sandbox.
	ErrKillPodSandbox = errors.New("KillPodSandboxError")

View on GitHub (pinned to b882c60b40)

Solutions

1. Inspect container logs: kubectl logs <pod> -c <container> and kubectl logs --previous for the crash output.
2. Check pod describe for OOMKilled/exit codes and events: kubectl describe pod <pod>.
3. Fix the root cause in the image/config (correct command, env, mounted secrets, resource limits).
4. If liveness probe is too aggressive, tune initialDelaySeconds/periodSeconds.

// Inspect container health before relying on sync results.
if isContainerCrashing(containerStatus) {
    // surface logs early to the operator instead of letting backoff grow silently
}

func isCrashLoopBackOff(result *container.SyncResult) bool {
    return result != nil && errors.Is(result.Error, container.ErrCrashLoopBackOff)
}

// ErrCrashLoopBackOff is a sentinel on SyncResult, not a thrown error.
// Read result.Error to detect it and surface logs/backoff to the operator.
if errors.Is(result.Error, container.ErrCrashLoopBackOff) {
    klog.InfoS("container in CrashLoopBackOff", "pod", klog.KObj(pod), "backoff", backoff)
}

When it happens

Trigger: During SyncPod, after a container exits (non-zero or repeatedly), the kubelet computes a backoff time and calls SyncResult.Fail(ErrCrashLoopBackOff, msg) to mark the container's state, surfacing as the CrashLoopBackOff pod condition/reason.

Common situations: Container crashes on startup: bad command/args, missing dependency, OOM kill, liveness probe failure killing it repeatedly, app panic, wrong image tag, misconfigured env/config, missing Secrets/ConfigMaps. Each restart shortens until backoff grows, producing CrashLoopBackOff.

Related errors

• pod sandboxes not found
• no matching container
• cAdvisor is unsupported in this build
• unsupported
• timed out waiting to connect to apiserver

AI-assisted analysis of kubernetes/kubernetes@b882c60b40 (2026-08-07). Data as JSON: /api/errors/9a3a61add7d9001a. Report an issue: GitHub.