{"record":{"id":"c8e17e1ac17da0c5","repo":"k3s-io/k3s","slug":"invalid-flag-use-cannot-use-disable-etcd-with","errorCode":null,"errorMessage":"invalid flag use; cannot use --disable-etcd with --datastore-endpoint","messagePattern":"invalid flag use; cannot use --disable-etcd with --datastore-endpoint","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/cli/server/server.go","lineNumber":266,"sourceCode":"\n\tserverConfig.ControlConfig.ClusterReset = cfg.ClusterReset\n\tserverConfig.ControlConfig.ClusterResetRestorePath = cfg.ClusterResetRestorePath\n\tserverConfig.ControlConfig.SystemDefaultRegistry = cfg.SystemDefaultRegistry\n\n\tif serverConfig.ControlConfig.SupervisorPort == 0 {\n\t\tserverConfig.ControlConfig.SupervisorPort = serverConfig.ControlConfig.HTTPSPort\n\t}\n\n\tif serverConfig.ControlConfig.DisableETCD && serverConfig.ControlConfig.JoinURL == \"\" {\n\t\treturn errors.New(\"invalid flag use; --server is required with --disable-etcd\")\n\t}\n\n\tif serverConfig.ControlConfig.Datastore.Endpoint != \"\" && serverConfig.ControlConfig.DisableAPIServer {\n\t\treturn errors.New(\"invalid flag use; cannot use --disable-apiserver with --datastore-endpoint\")\n\t}\n\n\tif serverConfig.ControlConfig.Datastore.Endpoint != \"\" && serverConfig.ControlConfig.DisableETCD {\n\t\treturn errors.New(\"invalid flag use; cannot use --disable-etcd with --datastore-endpoint\")\n\t}\n\n\tif serverConfig.ControlConfig.DisableAPIServer {\n\t\t// Servers without a local apiserver need to connect to the apiserver via the proxy load-balancer.\n\t\tserverConfig.ControlConfig.APIServerPort = cmds.AgentConfig.LBServerPort\n\t\t// If the supervisor and externally-facing apiserver are not on the same port, the proxy will\n\t\t// have a separate load-balancer for the apiserver that we need to use instead.\n\t\tif serverConfig.ControlConfig.SupervisorPort != serverConfig.ControlConfig.HTTPSPort {\n\t\t\tserverConfig.ControlConfig.APIServerPort = cmds.AgentConfig.LBServerPort - 1\n\t\t}\n\t}\n\n\tif cmds.AgentConfig.FlannelIface != \"\" && len(cmds.AgentConfig.NodeIP.Value()) == 0 {\n\t\tip, err := util.GetIPFromInterface(cmds.AgentConfig.FlannelIface)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tcmds.AgentConfig.NodeIP.Set(ip)","sourceCodeStart":248,"sourceCodeEnd":284,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/cli/server/server.go#L248-L284","documentation":"--disable-etcd marks a server that joins an embedded-etcd cluster through a peer via --server, while --datastore-endpoint selects an external datastore. Setting both leaves the node with two contradictory data-plane instructions, so startup fails fast.","triggerScenarios":"`k3s server --disable-etcd --datastore-endpoint=postgres://...`, or K3S_DATASTORE_ENDPOINT exported in the unit file while config.yaml sets `disable-etcd: true`.","commonSituations":"Flags left over after converting cluster topology; automation templates that set both 'HA' options defensively; env-var datastore config invisible to the operator reading only config.yaml.","solutions":["For external datastores, drop --disable-etcd entirely","For embedded-etcd joining, drop --datastore-endpoint and use --server <url> --token <token>","Unset K3S_DATASTORE_ENDPOINT / K3S_DATASTORE_* variables if the cluster is embedded-etcd"],"exampleFix":"# before\nk3s server --disable-etcd --datastore-endpoint=postgres://u:p@db:5432/k3s\n\n# after\nk3s server --datastore-endpoint=postgres://u:p@db:5432/k3s","handlingStrategy":"validation","validationCode":"# reject disable-etcd + datastore-endpoint combo\nif printf '%s' \"$@\" | grep -q -- '--disable-etcd' && { printf '%s' \"$@ $K3S_DATASTORE_ENDPOINT\" | grep -qE '(--datastore-endpoint|K3S_DATASTORE_ENDPOINT=..)'; }; then\n  echo 'cannot use --disable-etcd with --datastore-endpoint'; exit 1\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pick exactly one data-plane mode per node: embedded-etcd join OR external datastore","unset K3S_DATASTORE_ENDPOINT in units for embedded-etcd clusters","Periodically diff rendered systemd units against the intended topology"],"tags":["datastore","etcd","configuration","ha"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}