{"record":{"id":"a75d2408e9be1da3","repo":"containerd/containerd","slug":"failed-to-get-sandbox-runtime-w","errorCode":null,"errorMessage":"failed to get sandbox runtime: %w","messagePattern":"failed to get sandbox runtime: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cri/server/container_create.go","lineNumber":237,"sourceCode":"\tdefer func() {\n\t\tif retErr != nil {\n\t\t\t// Cleanup the volatile container root directory.\n\t\t\tif err := c.os.RemoveAll(volatileContainerRootDir); err != nil {\n\t\t\t\tlog.G(r.ctx).WithError(err).Errorf(\n\t\t\t\t\t\"Failed to remove volatile container root directory %q\",\n\t\t\t\t\tvolatileContainerRootDir,\n\t\t\t\t)\n\t\t\t}\n\t\t}\n\t}()\n\n\tplatform, err := c.sandboxService.SandboxPlatform(r.ctx, r.sandbox.Sandboxer, r.sandboxID)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to query sandbox platform: %w\", err)\n\t}\n\tociRuntime, err := c.getPodSandboxRuntime(r.sandboxID)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to get sandbox runtime: %w\", err)\n\t}\n\n\t// mutate the extra CRI volume mounts from the runtime spec to properly specify the OCI image volume mount requests as bind mounts for this container\n\terr = c.mutateMounts(r.ctx, r.containerConfig.GetMounts(), c.RuntimeSnapshotter(r.ctx, ociRuntime), r.sandboxID, platform)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to mount image volume: %w\", err)\n\t}\n\n\tvar volumeMounts []*runtime.Mount\n\tif !c.config.IgnoreImageDefinedVolumes {\n\t\t// create a list of image volume mounts from the image spec that are not also already in the runtime config volume list\n\t\tvolumeMounts = c.volumeMounts(platform, containerRootDir, r.containerConfig, r.imageConfig)\n\t} else if len(r.imageConfig.Volumes) != 0 {\n\t\tlog.G(r.ctx).Debugf(\"Ignoring volumes defined in image %v because IgnoreImageDefinedVolumes is set\", r.imageID)\n\t}\n\n\truntimeHandler, ok := c.runtimeHandlers[r.sandboxRuntimeHandler]\n\tif !ok {","sourceCodeStart":219,"sourceCodeEnd":255,"githubUrl":"https://github.com/containerd/containerd/blob/4246446a2bf7d03837b0244118d858799393bd80/internal/cri/server/container_create.go#L219-L255","documentation":"createContainer resolves which OCI runtime (runc, kata, etc.) serves the container's pod sandbox via c.getPodSandboxRuntime(r.sandboxID), which maps the sandbox's runtime handler to a configured runtime. If no matching runtime configuration exists or the lookup fails, this error is returned and container creation stops. It is a configuration/resolution error inside containerd's CRI plugin.","triggerScenarios":"The sandbox's runtime handler is not present in the [plugins.\"io.containerd.grpc.v1.cri\".containerd.runtimes] table; sandbox metadata is missing or its RuntimeHandler field is empty/mismatched; a CRI RuntimeHandler registered at pod time was removed from config before container create.","commonSituations":"Kubelet runtimeRequestHandler / RuntimeClass referencing a handler name that differs in spelling from containerd config; config.toml edited (handler renamed/removed) and containerd reloaded while pods still reference the old handler; typo like 'kata-containers' vs 'kata'.","solutions":["Compare the sandbox's runtime handler (crictl inspectp the pod) with the runtimes table in /etc/containerd/config.toml","Add or correct the missing runtime entry and restart containerd (systemctl restart containerd)","If the handler was intentionally removed, delete/recreate the affected pods so new sandboxes use a valid handler","Check containerd logs immediately after this error for the exact handler name that failed to resolve"],"exampleFix":"// before — handler missing in config.toml\n[plugins.\"io.containerd.grpc.v1.cri\".containerd.runtimes.runc]\n  runtime_type = \"io.containerd.runc.v2\"\n// after — add the handler the sandbox expects\n[plugins.\"io.containerd.grpc.v1.cri\".containerd.runtimes.kata]\n  runtime_type = \"io.containerd.runc.v2\"\n  [plugins.\"io.containerd.grpc.v1.cri\".containerd.runtimes.kata.options]\n    BinaryName = \"/usr/bin/kata-runtime\"","handlingStrategy":"validation","validationCode":"// Before rollout, verify every RuntimeClass handler used by pods is configured in containerd\nconst configured = ['runc', 'kata']; // parse from `containerd config dump`\nfor (const rc of runtimeClasses) {\n  if (!configured.includes(rc.handler)) {\n    throw new Error(`RuntimeClass ${rc.name}: handler '${rc.handler}' not in containerd runtimes`);\n  }\n}","typeGuard":"function isSandboxRuntimeError(err) {\n  return err instanceof Error &&\n    String(err.message).includes('failed to get sandbox runtime');\n}","tryCatchPattern":"try {\n  await criClient.createContainer(sandboxId, cfg);\n} catch (err) {\n  if (isSandboxRuntimeError(err)) {\n    throw new ConfigMismatchError('sandbox runtime handler not resolvable to configured runtime — fix /etc/containerd/config.toml runtimes table', err);\n  }\n  throw err;\n}","preventionTips":["Keep runtime handler names in Kubernetes RuntimeClass identical (case-sensitive) to config.toml keys","Never remove a runtime entry from config.toml while pods using it exist; drain first","Validate config.toml with `containerd config dump` after edits before restarting the daemon","Pin containerd config via a configuration management tool to prevent drift across nodes"],"tags":["containerd","cri","runtime-handler","configuration"],"backgroundTag":"runtime-handler-not-found","analyzedSha":"4246446a2bf7d03837b0244118d858799393bd80","analyzedAt":"2026-09-02T00:14:43.053Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}