{"record":{"id":"acde0ac83d6a5d1a","repo":"k3s-io/k3s","slug":"embedded-registry-mirror-requires-embedded-contain","errorCode":null,"errorMessage":"embedded registry mirror requires embedded containerd","messagePattern":"embedded registry mirror requires embedded containerd","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/run.go","lineNumber":119,"sourceCode":"\t}\n\t// The net/bridge/bridge-nf-call-{ip,ip6}tables sysctls are only required by kube-proxy\n\t// and flannel. When both are disabled the node is using an alternative CNI, so leave\n\t// these sysctls untouched for the administrator to manage. See\n\t// https://github.com/k3s-io/k3s/issues/14022. The flannel backend is compared against the\n\t// \"none\" literal rather than flannel.BackendNone to avoid importing the flannel package,\n\t// which registers all flannel backends via init().\n\tsetBridgeFilter := !config.KubeProxyDisabled(ctx, nodeConfig, proxy) || nodeConfig.Flannel.Backend != \"none\"\n\tsyssetup.Configure(enableIPv6, setBridgeFilter, conntrackConfig)\n\tnodeConfig.AgentConfig.EnableIPv4 = enableIPv4\n\tnodeConfig.AgentConfig.EnableIPv6 = enableIPv6\n\n\tif err := executor.Bootstrap(ctx, nodeConfig, cfg); err != nil {\n\t\treturn err\n\t}\n\n\tif nodeConfig.EmbeddedRegistry {\n\t\tif nodeConfig.Docker || nodeConfig.ContainerRuntimeEndpoint != \"\" {\n\t\t\treturn errors.New(\"embedded registry mirror requires embedded containerd\")\n\t\t}\n\n\t\tif err := spegel.DefaultRegistry.Start(ctx, nodeConfig, executor.CRIReadyChan()); err != nil {\n\t\t\treturn errors.WithMessage(err, \"failed to start embedded registry\")\n\t\t}\n\t}\n\n\tif nodeConfig.SupervisorMetrics {\n\t\tif err := metrics.DefaultMetrics.Start(ctx, nodeConfig); err != nil {\n\t\t\treturn errors.WithMessage(err, \"failed to serve metrics\")\n\t\t}\n\t}\n\n\tif nodeConfig.EnablePProf {\n\t\tif err := profile.DefaultProfiler.Start(ctx, nodeConfig); err != nil {\n\t\t\treturn errors.WithMessage(err, \"failed to serve pprof\")\n\t\t}\n\t}","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/agent/run.go#L101-L137","documentation":"The embedded registry mirror (spegel) requires pods to pull through k3s's own containerd so it can intercept and serve pulls. If the node is configured to use an external runtime (--docker or --container-runtime-endpoint), k3s cannot hook image pulls, so enabling --embedded-registry together with either flag fails fast during agent startup.","triggerScenarios":"Passing --embedded-registry on a node that also has --docker or --container-runtime-endpoint set (via CLI flags or /etc/rancher/k3s/config.yaml).","commonSituations":"Teams enabling the embedded registry on existing Docker-based nodes; config.yaml retaining old --docker entries after adding the new registry flag; GitOps templates merging both options.","solutions":["Remove --docker and --container-runtime-endpoint from the node's flags/config so it uses embedded containerd, then restart k3s","Or disable --embedded-registry on nodes that must keep using an external runtime","Scan /etc/rancher/k3s/config.yaml and systemd unit drop-ins for leftover runtime flags after config merges"],"exampleFix":"# before\nk3s agent --docker --embedded-registry ... # -> embedded registry mirror requires embedded containerd\n\n# after\nk3s agent --embedded-registry ... # default embedded containerd","handlingStrategy":"validation","validationCode":"if nodeConfig.EmbeddedRegistry && (nodeConfig.Docker || nodeConfig.ContainerRuntimeEndpoint != \"\") {\n    return errors.New(\"--embedded-registry is incompatible with --docker / --container-runtime-endpoint\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate flag combinations in config management (Ansible/Helm values) before rollout","When enabling the embedded registry, remove leftover docker/runtime-endpoint keys from config.yaml","Document that spegel requires the embedded containerd socket"],"tags":["embedded-registry","spegel","containerd","docker","config"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}