{"record":{"id":"ea67935da6641e7e","repo":"k3s-io/k3s","slug":"flannel-configuration-not-defined","errorCode":null,"errorMessage":"Flannel configuration not defined","messagePattern":"Flannel configuration not defined","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/flannel/setup.go","lineNumber":176,"sourceCode":"\tcniConfJSON := cniConf\n\tif goruntime.GOOS == \"windows\" {\n\t\textIface, err := LookupExtInterface(nodeConfig.Flannel.Iface, ipv4)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tcniConfJSON = strings.ReplaceAll(cniConfJSON, \"%IPV4_ADDRESS%\", extIface.IfaceAddr.String())\n\t\tcniConfJSON = strings.ReplaceAll(cniConfJSON, \"%CLUSTER_CIDR%\", nodeConfig.AgentConfig.ClusterCIDR.String())\n\t\tcniConfJSON = strings.ReplaceAll(cniConfJSON, \"%SERVICE_CIDR%\", nodeConfig.AgentConfig.ServiceCIDR.String())\n\t}\n\n\treturn agentutil.WriteFile(p, cniConfJSON)\n}\n\nfunc createFlannelConf(nodeConfig *config.Node) error {\n\tlogrus.Debugf(\"Creating the flannel configuration for backend %s in file %s\", nodeConfig.Flannel.Backend, nodeConfig.Flannel.ConfFile)\n\tif nodeConfig.Flannel.ConfFile == \"\" {\n\t\treturn errors.New(\"Flannel configuration not defined\")\n\t}\n\tif nodeConfig.Flannel.ConfOverride {\n\t\tlogrus.Infof(\"Using custom flannel conf defined at %s\", nodeConfig.Flannel.ConfFile)\n\t\treturn nil\n\t}\n\tnm, err := findNetMode(nodeConfig.AgentConfig.ClusterCIDRs)\n\tif err != nil {\n\t\tlogrus.Fatalf(\"Flannel error checking netMode: %v\", err)\n\t\treturn err\n\t}\n\tconfJSON := flannelConf\n\tif nm.IPv4Enabled() {\n\t\tconfJSON = strings.ReplaceAll(confJSON, \"%IPV4_ENABLED%\", \"true\")\n\t\tif nm.IPv6Enabled() {\n\t\t\tfor _, cidr := range nodeConfig.AgentConfig.ClusterCIDRs {\n\t\t\t\tif utilsnet.IsIPv4(cidr.IP) {\n\t\t\t\t\tconfJSON = strings.ReplaceAll(confJSON, \"%CIDR%\", cidr.String())\n\t\t\t\t\tbreak","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/agent/flannel/setup.go#L158-L194","documentation":"createFlannelConf refuses to continue when nodeConfig.Flannel.ConfFile is empty. k3s normally populates ConfFile during agent startup with the path where the generated flannel config is written; hitting this error means the flannel sub-system was invoked before that defaulting happened, or the value was explicitly cleared. It protects against silently writing a config to an unspecified location.","triggerScenarios":"Calling the flannel setup path (library consumers, tests, or tools) on a config.Node that never went through the agent config defaulting that sets Flannel.ConfFile; explicitly setting the flannel conf path to an empty string.","commonSituations":"Embedding k3s agent code in another binary that builds config.Node manually; unit/integration harnesses that exercise flannel setup directly; a config template that unsets flannel-conf.","solutions":["Let the normal agent startup path populate Flannel.ConfFile (do not bypass the defaulting stage)","If configuring manually, set the conf file path explicitly, e.g. nodeConfig.Flannel.ConfFile = \"/run/flannel/flannel-conf.json\" or the standard /etc/rancher/k3s/flannel/conf location","Pass --flannel-conf=/path/to/conf when overriding so ConfFile is never empty"],"exampleFix":"// before\nnodeConfig.Flannel.ConfFile = \"\"\ncreateFlannelConf(nodeConfig) // -> Flannel configuration not defined\n\n// after\nnodeConfig.Flannel.ConfFile = \"/etc/rancher/k3s/flannel/conf.json\"\ncreateFlannelConf(nodeConfig)","handlingStrategy":"validation","validationCode":"func hasFlannelConfFile(nodeConfig *config.Node) error {\n    if nodeConfig.Flannel.ConfFile == \"\" {\n        return errors.New(\"Flannel.ConfFile must be set (agent defaulting skipped?)\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Library consumers: run the standard agent config defaulting before touching flannel setup","Never blank Flannel.ConfFile; if overriding, point --flannel-conf at a real file","Unit-test config.Node construction to assert ConfFile is non-empty"],"tags":["flannel","cni","config","internal-api"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}