containerd/containerd · error

failed to start sandbox %q: %w

Error message

failed to start sandbox %q: %w

What it means

RunPodSandbox could not start the sandbox container; StartSandbox returned an error and containerd wraps it with the sandbox ID before returning to the CRI client. This is the generic 'pod could not be started' failure from the CRI runtime service.

Source

Thrown at internal/cri/server/sandbox_run.go:320

	} else {
		log.G(ctx).Debugf("Skipping pause image pull for runtime handler %q (type=%q, sandboxer=%q, disable_pause_image_pull=true)",
			r.GetRuntimeHandler(), ociRuntime.Type, ociRuntime.Sandboxer)
	}

	ctrl, err := c.sandboxService.StartSandbox(ctx, sandbox.Sandboxer, id)
	if err != nil {
		var cerr podsandbox.CleanupErr
		if errors.As(err, &cerr) {
			cleanupErr = fmt.Errorf("failed to cleanup sandbox: %w", cerr)

			// Strip last error as cleanup error to handle separately
			if merr, ok := err.(interface{ Unwrap() []error }); ok {
				if errs := merr.Unwrap(); len(errs) > 0 {
					err = errs[0]
				}
			}
		}
		return nil, fmt.Errorf("failed to start sandbox %q: %w", id, err)
	}

	// Shutdown the sandbox if we fail before adding it to store.
	rollbackSandbox := true
	defer func() {
		if retErr != nil && rollbackSandbox {
			deferCtx, deferCancel := util.DeferContext()
			defer deferCancel()
			cleanupErr = c.sandboxService.ShutdownSandbox(deferCtx, sandbox.Sandboxer, id)
		}
	}()

	if ctrl.Address != "" {
		sandbox.Endpoint = sandboxstore.Endpoint{
			Version: ctrl.Version,
			Address: ctrl.Address,
		}
	}

View on GitHub (pinned to 4246446a2b)

Solutions

1. Inspect the wrapped cause with errors.Unwrap or %v output; fix the root error (missing image, bad handler, OCI failure).
2. Verify the pause/pod infra image exists locally or is pullable (crictl pull).
3. Check the runtime handler in the Pod's runtimeClassName matches a configured handler in containerd.toml.
4. Confirm the OCI runtime binary (runc/crun) exists and works on the node.

Example fix

// before: unclear why sandbox failed
// after: unwrap to log the root cause
_, err := runtimeClient.RunPodSandbox(ctx, req)
if err != nil {
    log.Errorf("RunPodSandbox: %v", err) // message includes sandbox id + root cause
    return err
}

// pre-flight on the node before creating pods
// crictl info | jq -r '.status.runtimeHandlers'
// crictl inspecti <pause-image>  # pause image present?
// which runc && runc --version

_, err := client.RunPodSandbox(ctx, req)
if err != nil {
    if retriable(err) { // transient runtime/OCI failures
        time.Sleep(backoff)
        return client.RunPodSandbox(ctx, req)
    }
    return fmt.Errorf("sandbox start failed, fix runtime config: %w", err)
}

When it happens

Trigger: c.sandboxService.StartSandbox(ctx, sandbox.Sandboxer, id) returns any error (image missing, runtime handler invalid, OCI spec creation failed, shim exited) after cleanup-error handling.

Common situations: Pause image not present and pull disabled/offline; invalid runtimeClass/handler name in Pod spec; wrong snapshotter; SELinux/apparmor denials; node resource exhaustion; incompatible OCI runtime binary.

Related errors

• untrusted workload with explicit runtime handler is not allo
• untrusted workload with host access is not allowed
• failed to query sandbox platform: %w
• unable to get sandbox %q runtime info: %w
• sandbox %q not found: %w

AI-assisted analysis of containerd/containerd@4246446a2b (2026-09-02). Data as JSON: /api/errors/798f4a77454b496d. Report an issue: GitHub.