k3s-io/k3s · error

cannot perform cluster-reset while server URL is set - remov

Error message

cannot perform cluster-reset while server URL is set - remove server from configuration before resetting

What it means

--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.

Source

Thrown at pkg/cli/server/server.go:486

	if cfg.ClusterReset {
		serverConfig.ControlConfig.ClusterInit = true
		serverConfig.ControlConfig.DisableAPIServer = true
		serverConfig.ControlConfig.DisableControllerManager = true
		serverConfig.ControlConfig.DisableScheduler = true
		serverConfig.ControlConfig.DisableCCM = true
		serverConfig.ControlConfig.DisableServiceLB = true
		serverConfig.ControlConfig.EtcdDisableSnapshots = true

		// If the supervisor and apiserver are on the same port, everything is running embedded
		// and we don't need the kubelet or containerd up to perform a cluster reset.
		if serverConfig.ControlConfig.SupervisorPort == serverConfig.ControlConfig.HTTPSPort {
			cfg.DisableAgent = true
		}

		// If the user uses the cluster-reset argument in a cluster that has a ServerURL, we must return an error
		// to remove the server flag on the configuration or in the cli
		if serverConfig.ControlConfig.JoinURL != "" {
			return errors.New("cannot perform cluster-reset while server URL is set - remove server from configuration before resetting")
		}

		dataDir, err := datadir.LocalHome(cfg.DataDir, false)
		if err != nil {
			return err
		}
		// delete local loadbalancers state for apiserver and supervisor servers
		loadbalancer.ResetLoadBalancer(filepath.Join(dataDir, "agent"), loadbalancer.SupervisorServiceName)
		loadbalancer.ResetLoadBalancer(filepath.Join(dataDir, "agent"), loadbalancer.APIServerServiceName)

		if cfg.ClusterResetRestorePath != "" {
			// at this point we're doing a restore. Check to see if we've
			// passed in a token and if not, check if the token file exists.
			// If it doesn't, return an error indicating the token is necessary.
			if cfg.Token == "" {
				tokenFile := filepath.Join(dataDir, "server", "token")
				if _, err := os.Stat(tokenFile); err != nil {
					if os.IsNotExist(err) {

View on GitHub (pinned to 6ba341e396)

Solutions

1. Remove --server from the CLI and delete the `server:` line from /etc/rancher/k3s/config.yaml (and K3S_URL env) before resetting
2. Run the reset on a node that was never joined, or on the seed server of the original cluster
3. After the reset completes, remove --cluster-reset from the service command to avoid accidental re-resets

Example fix

# before
# /etc/rancher/k3s/config.yaml
server: https://10.0.0.10:6443
# CLI: k3s server --cluster-reset

# after
# /etc/rancher/k3s/config.yaml  (server line removed)
# CLI: k3s server --cluster-reset

# guard before cluster reset
if printf '%s' "$@" | grep -q -- '--cluster-reset'; then
  if grep -qE '^server: ' /etc/rancher/k3s/config.yaml || printf '%s' "$@" | grep -qE -- '--server|K3S_URL='; then
    echo 'remove server URL before cluster-reset'; exit 1
  fi
fi

When it happens

Trigger: `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.

Common situations: 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.

Related errors

• invalid flag use; --cluster-reset required with --cluster-re
• Managed etcd cluster membership has been reset, restart with
• etcd-s3-timeout must be greater than 0s
• invalid flag use; --server is required with --disable-etcd
• invalid flag use; cannot use --disable-etcd with --datastore

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/b682612104f3c28a. Report an issue: GitHub.