{"record":{"id":"b682612104f3c28a","repo":"k3s-io/k3s","slug":"cannot-perform-cluster-reset-while-server-url-is-s","errorCode":null,"errorMessage":"cannot perform cluster-reset while server URL is set - remove server from configuration before resetting","messagePattern":"cannot perform cluster-reset while server URL is set - remove server from configuration before resetting","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/cli/server/server.go","lineNumber":486,"sourceCode":"\tif cfg.ClusterReset {\n\t\tserverConfig.ControlConfig.ClusterInit = true\n\t\tserverConfig.ControlConfig.DisableAPIServer = true\n\t\tserverConfig.ControlConfig.DisableControllerManager = true\n\t\tserverConfig.ControlConfig.DisableScheduler = true\n\t\tserverConfig.ControlConfig.DisableCCM = true\n\t\tserverConfig.ControlConfig.DisableServiceLB = true\n\t\tserverConfig.ControlConfig.EtcdDisableSnapshots = true\n\n\t\t// If the supervisor and apiserver are on the same port, everything is running embedded\n\t\t// and we don't need the kubelet or containerd up to perform a cluster reset.\n\t\tif serverConfig.ControlConfig.SupervisorPort == serverConfig.ControlConfig.HTTPSPort {\n\t\t\tcfg.DisableAgent = true\n\t\t}\n\n\t\t// If the user uses the cluster-reset argument in a cluster that has a ServerURL, we must return an error\n\t\t// to remove the server flag on the configuration or in the cli\n\t\tif serverConfig.ControlConfig.JoinURL != \"\" {\n\t\t\treturn errors.New(\"cannot perform cluster-reset while server URL is set - remove server from configuration before resetting\")\n\t\t}\n\n\t\tdataDir, err := datadir.LocalHome(cfg.DataDir, false)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\t// delete local loadbalancers state for apiserver and supervisor servers\n\t\tloadbalancer.ResetLoadBalancer(filepath.Join(dataDir, \"agent\"), loadbalancer.SupervisorServiceName)\n\t\tloadbalancer.ResetLoadBalancer(filepath.Join(dataDir, \"agent\"), loadbalancer.APIServerServiceName)\n\n\t\tif cfg.ClusterResetRestorePath != \"\" {\n\t\t\t// at this point we're doing a restore. Check to see if we've\n\t\t\t// passed in a token and if not, check if the token file exists.\n\t\t\t// If it doesn't, return an error indicating the token is necessary.\n\t\t\tif cfg.Token == \"\" {\n\t\t\t\ttokenFile := filepath.Join(dataDir, \"server\", \"token\")\n\t\t\t\tif _, err := os.Stat(tokenFile); err != nil {\n\t\t\t\t\tif os.IsNotExist(err) {","sourceCodeStart":468,"sourceCodeEnd":504,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/cli/server/server.go#L468-L504","documentation":"--cluster-reset wipes local datastore state to seed a fresh cluster; k3s refuses the operation when a server URL (--server / `server:` in config) is set, because resetting a node that is joined to an existing cluster would desync it from its peers. Reset is only valid on a node with no join configuration.","triggerScenarios":"`k3s server --cluster-reset --server https://10.0.0.10:6443`, or a config.yaml that still contains the `server:` entry from the original join while --cluster-reset is passed.","commonSituations":"Attempting disaster recovery on a downstream control-plane node instead of the first server; leftover `server:` key in config.yaml after the cluster was initially formed; automation adding --cluster-reset to every node uniformly.","solutions":["Remove --server from the CLI and delete the `server:` line from /etc/rancher/k3s/config.yaml (and K3S_URL env) before resetting","Run the reset on a node that was never joined, or on the seed server of the original cluster","After the reset completes, remove --cluster-reset from the service command to avoid accidental re-resets"],"exampleFix":"# before\n# /etc/rancher/k3s/config.yaml\nserver: https://10.0.0.10:6443\n# CLI: k3s server --cluster-reset\n\n# after\n# /etc/rancher/k3s/config.yaml  (server line removed)\n# CLI: k3s server --cluster-reset","handlingStrategy":"validation","validationCode":"# guard before cluster reset\nif printf '%s' \"$@\" | grep -q -- '--cluster-reset'; then\n  if grep -qE '^server: ' /etc/rancher/k3s/config.yaml || printf '%s' \"$@\" | grep -qE -- '--server|K3S_URL='; then\n    echo 'remove server URL before cluster-reset'; exit 1\n  fi\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run cluster-reset only on the seed/first server node, via an explicit one-shot command","Strip `server:` from config.yaml as part of any documented reset runbook step 1","Never automate --cluster-reset across many nodes in parallel"],"tags":["cluster-reset","recovery","etcd","configuration"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}