{"record":{"id":"5fc6eb7dc75000b9","repo":"k3s-io/k3s","slug":"unexpected-compressed-etcd-snapshot-contents","errorCode":null,"errorMessage":"unexpected compressed etcd snapshot contents","messagePattern":"unexpected compressed etcd snapshot contents","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/etcd/snapshot.go","lineNumber":185,"sourceCode":"\n\tsf, err := os.Open(snapshotPath)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tdefer sf.Close()\n\n\tfi, err := sf.Stat()\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\tzf, err := zip.NewReader(sf, fi.Size())\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\tif len(zf.File) != 1 {\n\t\treturn \"\", errors.New(\"unexpected compressed etcd snapshot contents\")\n\t}\n\n\tcf, err := zf.File[0].Open()\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tdefer cf.Close()\n\n\tof, err := os.OpenFile(unzipPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tdefer of.Close()\n\n\t_, err = io.Copy(of, cf)\n\treturn unzipPath, err\n}\n","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/etcd/snapshot.go#L167-L203","documentation":"Compressed etcd snapshots are zip archives holding exactly one member - the db file. unzipSnapshot opens the archive with zip.NewReader and rejects any archive whose entry count differs from 1, before attempting extraction.","triggerScenarios":"Passing a snapshot zip that was corrupted during copy/download (truncated so the central directory lists 0 or garbage entries), or a hand-made zip that wrapped the db plus extra files (checksums, metadata); also an unrelated zip file passed as --cluster-reset-restore-path.","commonSituations":"Restoring a snapshot pulled from S3/object storage with a partial download; zipping the whole snapshots directory instead of the single db file; snapshots taken by a different tool or newer format with extra entries.","solutions":["Inspect the archive: unzip -l <file> - it must contain exactly one entry.","Re-download or re-copy the snapshot and compare checksums against the source (s3 etag/md5).","If the zip is not recoverable, take a fresh snapshot (etcd-snapshot save) or restore from an uncompressed full-snapshot db file instead.","If the db was zipped manually, re-zip only the db file with no extra entries."],"exampleFix":"# before: zipped the whole directory\nzip snap.zip /var/lib/rancher/k3s/server/db/snapshots/*\n# after: archive must contain exactly the db file\nzip snap.zip /var/lib/rancher/k3s/server/db/snapshots/etcd-snapshot-x-y/on-demand-db-...","handlingStrategy":"validation","validationCode":"func snapshotZipHasSingleEntry(path string) (bool, error) {\n    zf, err := zip.OpenReader(path)\n    if err != nil { return false, err }\n    defer zf.Close()\n    return len(zf.File) == 1, nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Checksum snapshots at creation and re-verify after every copy/download.","Never hand-package snapshots; use the tooling's own save/zip output."],"tags":["etcd","snapshot","zip","restore"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}