{"record":{"id":"b77877ec5b095bd4","repo":"k3s-io/k3s","slug":"invalid-flag-use-cluster-reset-required-with","errorCode":null,"errorMessage":"invalid flag use; --cluster-reset required with --cluster-reset-restore-path","messagePattern":"invalid flag use; --cluster-reset required with --cluster-reset-restore-path","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/cli/server/server.go","lineNumber":246,"sourceCode":"\t\t\t\tEndpoint:      cfg.EtcdS3Endpoint,\n\t\t\t\tEndpointCA:    cfg.EtcdS3EndpointCA,\n\t\t\t\tFolder:        cfg.EtcdS3Folder,\n\t\t\t\tInsecure:      cfg.EtcdS3Insecure,\n\t\t\t\tProxy:         cfg.EtcdS3Proxy,\n\t\t\t\tRegion:        cfg.EtcdS3Region,\n\t\t\t\tSecretKey:     cfg.EtcdS3SecretKey,\n\t\t\t\tSessionToken:  cfg.EtcdS3SessionToken,\n\t\t\t\tSkipSSLVerify: cfg.EtcdS3SkipSSLVerify,\n\t\t\t\tRetention:     cfg.EtcdS3Retention,\n\t\t\t\tTimeout:       metav1.Duration{Duration: cfg.EtcdS3Timeout},\n\t\t\t}\n\t\t}\n\t} else {\n\t\tlogrus.Info(\"ETCD snapshots are disabled\")\n\t}\n\n\tif cfg.ClusterResetRestorePath != \"\" && !cfg.ClusterReset {\n\t\treturn errors.New(\"invalid flag use; --cluster-reset required with --cluster-reset-restore-path\")\n\t}\n\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","sourceCodeStart":228,"sourceCodeEnd":264,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/cli/server/server.go#L228-L264","documentation":"--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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Add --cluster-reset to the same invocation: `k3s server --cluster-reset --cluster-reset-restore-path=<snap>`","If the restore already completed, remove cluster-reset-restore-path from config.yaml / CLI / unit file","Keep reset/restore flags in a one-shot systemd override or manual command, never in the persistent config"],"exampleFix":"# before\nk3s server --cluster-reset-restore-path=/backups/etcd-snapshot.zip\n\n# after\nk3s server --cluster-reset --cluster-reset-restore-path=/backups/etcd-snapshot.zip","handlingStrategy":"validation","validationCode":"# refuse to start if restore path is set without cluster-reset\nif [ -n \"$RESTORE_PATH\" ]; then\n  case \" $* \" in *\" --cluster-reset\"*) ;; *) echo \"--cluster-reset required with --cluster-reset-restore-path\"; exit 1;; esac\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep reset/restore flags in one-shot commands, never in persistent config.yaml","Automate post-restore cleanup that strips cluster-reset flags from systemd units","Treat any cluster-reset* flag in config.yaml as config smell in reviews"],"tags":["cluster-reset","restore","etcd","backup","configuration"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}