k3s-io/k3s · error

invalid flag use; --cluster-reset required with --cluster-re

Error message

invalid flag use; --cluster-reset required with --cluster-reset-restore-path

What it means

--cluster-reset-restore-path names an etcd snapshot to restore from, and it is only consumed as part of a cluster reset. k3s rejects the path without --cluster-reset because otherwise the snapshot argument would be silently ignored on every normal restart.

Source

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

				Endpoint:      cfg.EtcdS3Endpoint,
				EndpointCA:    cfg.EtcdS3EndpointCA,
				Folder:        cfg.EtcdS3Folder,
				Insecure:      cfg.EtcdS3Insecure,
				Proxy:         cfg.EtcdS3Proxy,
				Region:        cfg.EtcdS3Region,
				SecretKey:     cfg.EtcdS3SecretKey,
				SessionToken:  cfg.EtcdS3SessionToken,
				SkipSSLVerify: cfg.EtcdS3SkipSSLVerify,
				Retention:     cfg.EtcdS3Retention,
				Timeout:       metav1.Duration{Duration: cfg.EtcdS3Timeout},
			}
		}
	} else {
		logrus.Info("ETCD snapshots are disabled")
	}

	if cfg.ClusterResetRestorePath != "" && !cfg.ClusterReset {
		return errors.New("invalid flag use; --cluster-reset required with --cluster-reset-restore-path")
	}

	serverConfig.ControlConfig.ClusterReset = cfg.ClusterReset
	serverConfig.ControlConfig.ClusterResetRestorePath = cfg.ClusterResetRestorePath
	serverConfig.ControlConfig.SystemDefaultRegistry = cfg.SystemDefaultRegistry

	if serverConfig.ControlConfig.SupervisorPort == 0 {
		serverConfig.ControlConfig.SupervisorPort = serverConfig.ControlConfig.HTTPSPort
	}

	if serverConfig.ControlConfig.DisableETCD && serverConfig.ControlConfig.JoinURL == "" {
		return errors.New("invalid flag use; --server is required with --disable-etcd")
	}

	if serverConfig.ControlConfig.Datastore.Endpoint != "" && serverConfig.ControlConfig.DisableAPIServer {
		return errors.New("invalid flag use; cannot use --disable-apiserver with --datastore-endpoint")
	}

View on GitHub (pinned to 6ba341e396)

Solutions

1. Add --cluster-reset to the same invocation: `k3s server --cluster-reset --cluster-reset-restore-path=<snap>`
2. If the restore already completed, remove cluster-reset-restore-path from config.yaml / CLI / unit file
3. Keep reset/restore flags in a one-shot systemd override or manual command, never in the persistent config

Example fix

# before
k3s server --cluster-reset-restore-path=/backups/etcd-snapshot.zip

# after
k3s server --cluster-reset --cluster-reset-restore-path=/backups/etcd-snapshot.zip

# refuse to start if restore path is set without cluster-reset
if [ -n "$RESTORE_PATH" ]; then
  case " $* " in *" --cluster-reset"*) ;; *) echo "--cluster-reset required with --cluster-reset-restore-path"; exit 1;; esac
fi

When it happens

Trigger: `k3s server --cluster-reset-restore-path=/var/lib/rancher/k3s/server/db/snapshots/etcd-snapshot.zip` without `--cluster-reset` on the same command line or in config.yaml.

Common situations: Disaster-recovery run where the operator forgot --cluster-reset; restore path left permanently in config.yaml or a systemd drop-in so every routine restart trips the check.

Related errors

• etcd-s3-timeout must be greater than 0s
• cannot perform cluster-reset while server URL is set - remov
• no etcd restore path was specified
• s3 configuration was not set
• etcd: snapshot path does not exist: %s

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