{"record":{"id":"46e3ac3b57212fb9","repo":"containerd/containerd","slug":"failed-to-find-runtime-handler-q","errorCode":null,"errorMessage":"failed to find runtime handler %q","messagePattern":"failed to find runtime handler %q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cri/server/container_create.go","lineNumber":256,"sourceCode":"\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 {\n\t\treturn \"\", fmt.Errorf(\"failed to find runtime handler %q\", r.sandboxRuntimeHandler)\n\t}\n\tlog.G(r.ctx).Debugf(\"Use OCI runtime %+v for sandbox %q and container %q\", ociRuntime, r.sandboxID, r.containerID)\n\n\timageName := (*r.containerdImage).Name()\n\tif name := r.containerConfig.GetImage().GetUserSpecifiedImage(); name != \"\" {\n\t\timageName = name\n\t}\n\n\tspec, err := c.buildContainerSpec(\n\t\tplatform,\n\t\tr.containerID,\n\t\tr.sandboxID,\n\t\tr.sandboxPid,\n\t\tr.NetNSPath,\n\t\tr.containerName,\n\t\timageName,\n\t\tr.containerConfig,\n\t\tr.podSandboxConfig,","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/containerd/containerd/blob/4246446a2bf7d03837b0244118d858799393bd80/internal/cri/server/container_create.go#L238-L274","documentation":"createContainer looks up the sandbox's runtime handler in the in-memory map c.runtimeHandlers (populated from containerd's CRI runtimes configuration). If the handler string stored on the sandbox (r.sandboxRuntimeHandler) is not a configured handler key, creation fails with 'failed to find runtime handler'. Unlike the sandbox-runtime error, this one is specifically about the handler registry map.","triggerScenarios":"r.sandboxRuntimeHandler references a handler absent from config.toml's runtimes table; the default runtime handler was renamed in config after the sandbox was created; containerd config failed to load runtimes (malformed TOML section) leaving the map missing entries.","commonSituations":"RuntimeClass in Kubernetes naming a handler ('kata-qemu') not configured in containerd; typo in the runtimes table key; containerd started with a generated config (k3s/kubeadm) that dropped custom runtimes; case-sensitivity mismatch in handler names.","solutions":["Run containerd config dump | grep runtimes to list configured handlers and confirm the exact handler name","Add the missing handler section to /etc/containerd/config.toml and restart containerd","Correct the Kubernetes RuntimeClass/handler name so it matches a configured handler exactly (case-sensitive)","Recreate the sandbox: sandboxes pin their handler at creation, so an existing pod keeps the stale name"],"exampleFix":"// before — RuntimeClass handler 'kata' not in containerd config\nkind: RuntimeClass\nhandler: kata\n// after — either configure handler 'kata' in config.toml or use an existing one\nkind: RuntimeClass\nhandler: runc","handlingStrategy":"validation","validationCode":"// Pre-check the handler exists before scheduling/creating\nconst { stdout } = await exec('containerd config dump');\nconst handlers = [...stdout.matchAll(/runtimes\\.([\\w.-]+)/g)].map(m => m[1]);\nif (!handlers.includes(sandboxRuntimeHandler)) {\n  throw new Error(`handler '${sandboxRuntimeHandler}' not configured; have: ${handlers.join(',')}`);\n}","typeGuard":"function isRuntimeHandlerNotFoundError(err) {\n  return err instanceof Error &&\n    /failed to find runtime handler \"[^\"]+\"/.test(err.message);\n}","tryCatchPattern":"try {\n  await criClient.createContainer(sandboxId, cfg);\n} catch (err) {\n  if (isRuntimeHandlerNotFoundError(err)) {\n    const handler = err.message.match(/\"([^\"]+)\"/)?.[1];\n    throw new HandlerNotConfiguredError(handler, err); // route to a node with that handler configured\n  }\n  throw err;\n}","preventionTips":["Mirror RuntimeClass handler names 1:1 with config.toml runtimes keys in a CI check","Recreate sandboxes after any runtime handler rename — old sandboxes pin the old name","Run containerd config dump on every node as a startup admission check","Guard against case/typo drift with a shared constants list of valid handlers"],"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"}