What causes "pod %s failed" in helm/helm?

Fetch the pod's status and logs: kubectl describe pod and kubectl logs --all-containers.

pod %s failed

Error message

pod %s failed

What it means

Returned by legacyWaiter.waitForPodSuccess (pkg/kube/wait.go:333) when a watched Pod's Status.Phase is PodFailed. --wait treats a failed Pod as terminal (the message names the pod), stopping the wait immediately instead of blocking until timeout.

Source

Thrown at pkg/kube/wait.go:333

	return false, nil
}

// waitForPodSuccess is a helper that waits for a pod to complete.
//
// This operates on an event returned from a watcher.
func (hw *legacyWaiter) waitForPodSuccess(obj runtime.Object, name string) (bool, error) {
	o, ok := obj.(*corev1.Pod)
	if !ok {
		return true, fmt.Errorf("expected %s to be a *v1.Pod, got %T", name, obj)
	}

	switch o.Status.Phase {
	case corev1.PodSucceeded:
		slog.Debug("pod succeeded", "pod", o.Name)
		return true, nil
	case corev1.PodFailed:
		slog.Error("pod failed", "pod", o.Name)
		return true, fmt.Errorf("pod %s failed", o.Name)
	case corev1.PodPending:
		slog.Debug("pod pending", "pod", o.Name)
	case corev1.PodRunning:
		slog.Debug("pod running", "pod", o.Name)
	case corev1.PodUnknown:
		slog.Debug("pod unknown", "pod", o.Name)
	}

	return false, nil
}

func (hw *legacyWaiter) contextWithTimeout(timeout time.Duration) (context.Context, context.CancelFunc) {
	return contextWithTimeout(hw.ctx, timeout)
}

View on GitHub (pinned to 2a29f1770b)

Solutions

Fetch the pod's status and logs: kubectl describe pod <name> and kubectl logs <name> --all-containers.
Fix the container failure (command, image, env, resource limits).
If the pod is doing one-shot work, model it as a Job with backoffLimit so retries happen before Helm fails.
Raise memory/CPU limits if the failure is OOMKilled/Evicted.

Example fix

# before: one-shot pod dies and fails the release
resources:
  limits:
    memory: 64Mi

# after: limits that fit the workload (and prefer a Job for retries)
resources:
  limits:
    memory: 256Mi

Defensive patterns

Strategy: try-catch

Try / catch

if err := installWithWait(); err != nil {
	if m := regexp.MustCompile(`pod (\S+) failed`).FindStringSubmatch(err.Error()); m != nil {
		// pull kubectl logs for m[1] and present the container failure
	}
}

Prevention

Model one-shot work as Jobs (with retries) rather than bare Pods.
Set resource limits that fit the container to avoid OOMKill/Eviction failures.
Verify image tags and entrypoints in CI before deploying with --wait.

When it happens

Trigger: helm install/upgrade --wait on a release with bare Pods (or hook pods) whose phase becomes Failed: container exits non-zero, image pull failure ends the pod, node pressure evicts with phase Failed, or OOMKill.

Common situations: Bare pod charts running setup jobs that crash; init containers failing on missing secrets; images with wrong entrypoints; memory limits causing OOMKilled containers.

Related errors

AI-assisted analysis of helm/helm@2a29f1770b (2026-08-15). Data as JSON: /api/errors/12922975b8ced306. Report an issue: GitHub.