k3s-io/k3s · error

unexpected compressed etcd snapshot contents

Error message

unexpected compressed etcd snapshot contents

What it means

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.

Source

Thrown at pkg/etcd/snapshot.go:185

	sf, err := os.Open(snapshotPath)
	if err != nil {
		return "", err
	}
	defer sf.Close()

	fi, err := sf.Stat()
	if err != nil {
		return "", err
	}

	zf, err := zip.NewReader(sf, fi.Size())
	if err != nil {
		return "", err
	}

	if len(zf.File) != 1 {
		return "", errors.New("unexpected compressed etcd snapshot contents")
	}

	cf, err := zf.File[0].Open()
	if err != nil {
		return "", err
	}
	defer cf.Close()

	of, err := os.OpenFile(unzipPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
	if err != nil {
		return "", err
	}
	defer of.Close()

	_, err = io.Copy(of, cf)
	return unzipPath, err
}

View on GitHub (pinned to 6ba341e396)

Solutions

1. Inspect the archive: unzip -l <file> - it must contain exactly one entry.
2. Re-download or re-copy the snapshot and compare checksums against the source (s3 etag/md5).
3. If the zip is not recoverable, take a fresh snapshot (etcd-snapshot save) or restore from an uncompressed full-snapshot db file instead.
4. If the db was zipped manually, re-zip only the db file with no extra entries.

Example fix

# before: zipped the whole directory
zip snap.zip /var/lib/rancher/k3s/server/db/snapshots/*
# after: archive must contain exactly the db file
zip snap.zip /var/lib/rancher/k3s/server/db/snapshots/etcd-snapshot-x-y/on-demand-db-...

func snapshotZipHasSingleEntry(path string) (bool, error) {
    zf, err := zip.OpenReader(path)
    if err != nil { return false, err }
    defer zf.Close()
    return len(zf.File) == 1, nil
}

When it happens

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

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

Related errors

• etcd: snapshot path does not exist: %s
• etcd: snapshot path must be a file, not a directory: %s
• no snapshots given for removal
• invalid output format:
• etcd-snapshot-reconcile-interval must be greater than 0s

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