containerd/containerd · error

sandbox %q not found: %w

Error message

sandbox %q not found: %w

What it means

StartContainer looks up the container's parent pod sandbox (meta.SandboxID) in the internal sandbox store before starting the container. If the sandbox record is gone, this wrapped error is returned with the underlying store error. containerd requires a live, known sandbox to attach the container to (network namespace, runtime handler, endpoint, etc.).

Source

Thrown at internal/cri/server/container_start.go:86

				status.Pid = 0
				status.FinishedAt = time.Now().UnixNano()
				status.ExitCode = errorStartExitCode
				status.Reason = errorStartReason
				status.Message = retErr.Error()
				return status, nil
			}); err != nil {
				log.G(ctx).WithError(err).Errorf("failed to set start failure state for container %q", id)
			}
		}
		if err := resetContainerStarting(cntr); err != nil {
			log.G(ctx).WithError(err).Errorf("failed to reset starting state for container %q", id)
		}
	}()

	// Get sandbox config from sandbox store.
	sandbox, err := c.sandboxStore.Get(meta.SandboxID)
	if err != nil {
		return nil, fmt.Errorf("sandbox %q not found: %w", meta.SandboxID, err)
	}
	sandboxID := meta.SandboxID
	if sandbox.Status.Get().State != sandboxstore.StateReady {
		return nil, fmt.Errorf("sandbox container %q is not running", sandboxID)
	}
	span.SetAttributes(tracing.Attribute("sandbox.id", sandboxID))

	ioCreation := func(id string) (_ containerdio.IO, err error) {
		stdoutWC, stderrWC, err := c.createContainerLoggers(meta.LogPath, config.GetTty())
		if err != nil {
			return nil, fmt.Errorf("failed to create container loggers: %w", err)
		}
		cntr.IO.AddOutput("log", stdoutWC, stderrWC)
		cntr.IO.Pipe()
		return cntr.IO, nil
	}

	// Recheck target container validity in Linux namespace options.

View on GitHub (pinned to 4246446a2b)

Solutions

1. Check that the pod sandbox still exists (crictl pods / PodSandboxStatus) before starting containers in it.
2. If the sandbox is gone, stop and remove the orphan container and let the higher-level runtime (kubelet) recreate the pod.
3. Investigate why the sandbox was removed: look for StopPodSandbox/RemovePodSandbox events around the failure time in containerd logs.
4. After a containerd restart, verify sandbox recovery; if sandboxes were not recovered, restart the node agent so pods are rescheduled.
5. Ensure CRI clients don't race sandbox removal against container start; serialize pod teardown before container operations.

Example fix

// before: start container unconditionally
runtimeService.StartContainer(containerID)
// after: verify sandbox is present and ready first
sb, err := runtimeService.PodSandboxStatus(sandboxID)
if err != nil {
    return fmt.Errorf("sandbox %s gone, recreate pod: %w", sandboxID, err)
}
runtimeService.StartContainer(containerID)

if _, err := runtimeService.PodSandboxStatus(ctx, sandboxID); err != nil {
    return fmt.Errorf("sandbox %s missing, recreate pod before starting containers: %w", sandboxID, err)
}

func sandboxExists(ctx context.Context, rs runtime.RuntimeService, id string) bool {
    _, err := rs.PodSandboxStatus(ctx, id)
    return err == nil
}

_, err := runtimeService.StartContainer(ctx, containerID)
if err != nil && strings.Contains(err.Error(), "sandbox") && strings.Contains(err.Error(), "not found") {
    return recreatePod(sandboxID) // sandbox is gone; let kubelet recreate
}

When it happens

Trigger: StartContainer is called with a container whose SandboxID no longer exists in the sandbox store — typically the pod sandbox was removed (StopSandbox/RemoveSandbox) or the store entry was evicted/cleaned while the container record still exists.

Common situations: Kubelet starting a container of a pod that is concurrently being torn down; sandbox garbage collection after a failed pod; stale container entries after containerd restart where sandboxes were not recovered; misconfigured pod pointing at a deleted sandbox.

Related errors

• can't find sandbox for TaskExit event: %w
• 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

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