{"record":{"id":"99371fba2bbfee76","repo":"k3s-io/k3s","slug":"etcd-snapshot-path-does-not-exist-s","errorCode":null,"errorMessage":"etcd: snapshot path does not exist: %s","messagePattern":"etcd: snapshot path does not exist: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/etcd/etcd.go","lineNumber":413,"sourceCode":"\t\t\t\t\treturn errors.New(\"cannot use S3 config secret when restoring snapshot; configuration must be set in CLI or config file\")\n\t\t\t\t}\n\t\t\t\treturn errors.WithMessage(err, \"failed to initialize S3 client\")\n\t\t\t}\n\t\t\tdir, err := snapshotDir(e.config, true)\n\t\t\tif err != nil {\n\t\t\t\treturn errors.WithMessage(err, \"failed to get the snapshot dir\")\n\t\t\t}\n\t\t\tpath, err := s3client.Download(ctx, e.config.ClusterResetRestorePath, dir)\n\t\t\tif err != nil {\n\t\t\t\treturn errors.WithMessage(err, \"failed to download snapshot from S3\")\n\t\t\t}\n\t\t\te.config.ClusterResetRestorePath = path\n\t\t\tlogrus.Infof(\"S3 download complete for %s\", e.config.ClusterResetRestorePath)\n\t\t}\n\n\t\tinfo, err := os.Stat(e.config.ClusterResetRestorePath)\n\t\tif os.IsNotExist(err) {\n\t\t\treturn fmt.Errorf(\"etcd: snapshot path does not exist: %s\", e.config.ClusterResetRestorePath)\n\t\t}\n\t\tif info.IsDir() {\n\t\t\treturn fmt.Errorf(\"etcd: snapshot path must be a file, not a directory: %s\", e.config.ClusterResetRestorePath)\n\t\t}\n\t\tif err := e.Restore(ctx); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\tif err := e.setName(true); err != nil {\n\t\treturn err\n\t}\n\t// touch a file to avoid multiple resets\n\tif err := os.WriteFile(e.ResetFile(), []byte{}, 0600); err != nil {\n\t\treturn err\n\t}\n\n\treturn e.newCluster(ctx, wg, true)","sourceCodeStart":395,"sourceCodeEnd":431,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/etcd/etcd.go#L395-L431","documentation":"During cluster reset with --cluster-reset-restore-path, after an optional S3 download, k3s stats the snapshot path and requires an existing regular file. os.Stat returning IsNotExist produces this error - the configured snapshot path is not present on this node (a failed S3 download would already have failed earlier with 'failed to download snapshot from S3').","triggerScenarios":"Running `k3s server --cluster-reset --cluster-reset-restore-path=/path/snapshot.db` where the path is misspelled, on a different node than where the file lives, or the file was deleted/moved (pkg/etcd/etcd.go:411-414).","commonSituations":"Restoring on a new node from a snapshot copied to a different location; relative path resolved against k3s's working dir; snapshot pruned by retention; scp of the snapshot never completed.","solutions":["Verify the file exists on this node with an absolute path: `ls -l /var/lib/rancher/k3s/server/db/snapnapshots/` (default snapshot dir: /var/lib/rancher/k3s/server/db/snapshots) and use the full file path.","If restoring on a different node, copy the snapshot file there first (or configure S3 so it is downloaded automatically).","List available snapshots with `k3s etcd-snapshot ls` and re-run using the exact on-demand path or name."],"exampleFix":"# before\nk3s server \\\n  --cluster-reset \\\n  --cluster-reset-restore-path=/var/lib/rancher/k3s/server/db/snapshots\n\n# after (point at the snapshot FILE, not a made-up path)\nk3s server \\\n  --cluster-reset \\\n  --cluster-reset-restore-path=/var/lib/rancher/k3s/server/db/snapshots/etcd-snapshot-1723680000-0.db","handlingStrategy":"validation","validationCode":"// Pre-check the snapshot path before invoking cluster-reset restore:\ninfo, err := os.Stat(snapshotPath)\nif os.IsNotExist(err) {\n    log.Fatalf(\"snapshot %s does not exist on this node - copy it here or check the S3 config\", snapshotPath)\n}\nif err != nil { log.Fatal(err) }\nif info.IsDir() { log.Fatalf(\"%s is a directory; pass the .db snapshot file\", snapshotPath) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass absolute paths to --cluster-reset-restore-path.","Automate restore runbooks: copy snapshot, ls -l it, then start with the reset flags.","Keep snapshot retention/monitoring so restores never point at pruned files."],"tags":["etcd","snapshot","restore","cluster-reset","k3s"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}