{"record":{"id":"798f4a77454b496d","repo":"containerd/containerd","slug":"failed-to-start-sandbox-q-w","errorCode":null,"errorMessage":"failed to start sandbox %q: %w","messagePattern":"failed to start sandbox %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cri/server/sandbox_run.go","lineNumber":320,"sourceCode":"\t} else {\n\t\tlog.G(ctx).Debugf(\"Skipping pause image pull for runtime handler %q (type=%q, sandboxer=%q, disable_pause_image_pull=true)\",\n\t\t\tr.GetRuntimeHandler(), ociRuntime.Type, ociRuntime.Sandboxer)\n\t}\n\n\tctrl, err := c.sandboxService.StartSandbox(ctx, sandbox.Sandboxer, id)\n\tif err != nil {\n\t\tvar cerr podsandbox.CleanupErr\n\t\tif errors.As(err, &cerr) {\n\t\t\tcleanupErr = fmt.Errorf(\"failed to cleanup sandbox: %w\", cerr)\n\n\t\t\t// Strip last error as cleanup error to handle separately\n\t\t\tif merr, ok := err.(interface{ Unwrap() []error }); ok {\n\t\t\t\tif errs := merr.Unwrap(); len(errs) > 0 {\n\t\t\t\t\terr = errs[0]\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn nil, fmt.Errorf(\"failed to start sandbox %q: %w\", id, err)\n\t}\n\n\t// Shutdown the sandbox if we fail before adding it to store.\n\trollbackSandbox := true\n\tdefer func() {\n\t\tif retErr != nil && rollbackSandbox {\n\t\t\tdeferCtx, deferCancel := util.DeferContext()\n\t\t\tdefer deferCancel()\n\t\t\tcleanupErr = c.sandboxService.ShutdownSandbox(deferCtx, sandbox.Sandboxer, id)\n\t\t}\n\t}()\n\n\tif ctrl.Address != \"\" {\n\t\tsandbox.Endpoint = sandboxstore.Endpoint{\n\t\t\tVersion: ctrl.Version,\n\t\t\tAddress: ctrl.Address,\n\t\t}\n\t}","sourceCodeStart":302,"sourceCodeEnd":338,"githubUrl":"https://github.com/containerd/containerd/blob/4246446a2bf7d03837b0244118d858799393bd80/internal/cri/server/sandbox_run.go#L302-L338","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped cause with errors.Unwrap or %v output; fix the root error (missing image, bad handler, OCI failure).","Verify the pause/pod infra image exists locally or is pullable (crictl pull).","Check the runtime handler in the Pod's runtimeClassName matches a configured handler in containerd.toml.","Confirm the OCI runtime binary (runc/crun) exists and works on the node."],"exampleFix":"// before: unclear why sandbox failed\n// after: unwrap to log the root cause\n_, err := runtimeClient.RunPodSandbox(ctx, req)\nif err != nil {\n    log.Errorf(\"RunPodSandbox: %v\", err) // message includes sandbox id + root cause\n    return err\n}","handlingStrategy":"retry","validationCode":"// pre-flight on the node before creating pods\n// crictl info | jq -r '.status.runtimeHandlers'\n// crictl inspecti <pause-image>  # pause image present?\n// which runc && runc --version","typeGuard":null,"tryCatchPattern":"_, err := client.RunPodSandbox(ctx, req)\nif err != nil {\n    if retriable(err) { // transient runtime/OCI failures\n        time.Sleep(backoff)\n        return client.RunPodSandbox(ctx, req)\n    }\n    return fmt.Errorf(\"sandbox start failed, fix runtime config: %w\", err)\n}","preventionTips":["Pre-pull the pause image and pin a valid version in containerd config.","Validate runtimeClass/handler names against containerd.toml before scheduling pods.","Keep OCI runtime binaries updated and on PATH."],"tags":["cri","sandbox","pod-startup","containerd"],"backgroundTag":"sandbox-start-failed","analyzedSha":"4246446a2bf7d03837b0244118d858799393bd80","analyzedAt":"2026-09-02T00:14:43.053Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}