k3s-io/k3s · critical

error extracting zstd-compressed body: %v

Error message

error extracting zstd-compressed body: %v

What it means

On first boot (or upgrade) k3s extracts the data-dir payload embedded in the binary (data.Asset -> untar.Untar at cmd/k3s/main.go:303). The payload is a zstd-compressed tarball; k3s zstd.Newreader is created with a hard decode-memory cap (tarfile.MaxDecoderMemory). This error means the zstd stream itself could not be initialized: the data is not valid zstd, is truncated, or would require more than the decoder memory cap.

Source

Thrown at pkg/untar/untar.go:44

// Untar reads the zstd-compressed tar file from r and writes it into dir.
func Untar(r io.Reader, dir string) error {
	return untar(r, dir)
}

func untar(r io.Reader, dir string) (err error) {
	t0 := time.Now()
	nFiles := 0
	madeDir := map[string]bool{}
	defer func() {
		td := time.Since(t0)
		if err != nil {
			logrus.Printf("error extracting tarball into %s after %d files, %d dirs, %v: %v", dir, nFiles, len(madeDir), td, err)
		}
	}()
	zr, err := zstd.NewReader(r, zstd.WithDecoderMaxMemory(tarfile.MaxDecoderMemory))
	if err != nil {
		return fmt.Errorf("error extracting zstd-compressed body: %v", err)
	}
	defer zr.Close()
	tr := tar.NewReader(zr)
	loggedChtimesError := false
	for {
		f, err := tr.Next()
		if err == io.EOF {
			break
		}
		if err != nil {
			logrus.Printf("tar reading error: %v", err)
			return fmt.Errorf("tar error: %v", err)
		}
		if !validRelPath(f.Name) {
			return fmt.Errorf("tar contained invalid name error %q", f.Name)
		}
		rel := filepath.FromSlash(f.Name)
		abs := filepath.Join(dir, rel)

View on GitHub (pinned to 6ba341e396)

Solutions

1. Verify the binary checksum against the release's sha256sums file; re-download and replace on mismatch.
2. Check disk/filesystem health on the node (dmesg for I/O errors) if checksums pass locally but corruption recurs.
3. If building from source, ensure the embedded data asset generation completed (make) before the final link.
4. After replacing the binary, clear any half-extracted '<data-dir>-tmp' leftovers and restart k3s.

Example fix

# before
curl -LO https://.../k3s  # interrupted transfer
./k3s server  # error extracting zstd-compressed body

# after
sha256sum -c sha256sums.txt  # or re-download
./k3s server

// Verify the binary before first start
// sha256sum k3s; compare with official sha256sums.txt for the release
if !checksumMatches("k3s", wantSHA) {
    log.Fatal("k3s binary checksum mismatch - redownload")
}

When it happens

Trigger: Startup calls untar() and zstd.NewReader(r, WithDecoderMaxMemory(...)) fails: the embedded build asset is corrupt (truncated or bit-flipped binary), the binary was modified/repacked improperly, or the compressed stream declares window sizes exceeding the decoder limit.

Common situations: A k3s binary downloaded partially or corrupted in transit; binaries rebuilt/repacked with a modified or incompatible embedded data blob; filesystem-level corruption on the binary's storage; extremely uncommon on official release artifacts.

Related errors

• tar error: %v
• failed to verify directory %s
• no entries found in %s
• failed %d hash verifications
• unhandled cgroup mode

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