anomalyco/sst · error

failed to read tar entry: %w

Error message

failed to read tar entry: %w

What it means

While iterating entries with tar.NewReader's tr.Next(), any error other than io.EOF is wrapped as "failed to read tar entry". This means the tar stream itself is malformed or the read failed midway — the gzip header was valid but the body is corrupt, truncated, or uses unsupported tar features.

Source

Thrown at pkg/runtime/python/build.go:418

	if err != nil {
		return fmt.Errorf("failed to open archive: %w", err)
	}
	defer f.Close()

	gz, err := gzip.NewReader(f)
	if err != nil {
		return fmt.Errorf("failed to create gzip reader: %w", err)
	}
	defer gz.Close()

	tr := tar.NewReader(gz)
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			break
		}
		if err != nil {
			return fmt.Errorf("failed to read tar entry: %w", err)
		}

		target := filepath.Join(destDir, hdr.Name)
		// Guard against tar slip
		if !strings.HasPrefix(filepath.Clean(target), filepath.Clean(destDir)+string(os.PathSeparator)) {
			return fmt.Errorf("illegal file path in tar: %s", hdr.Name)
		}

		switch hdr.Typeflag {
		case tar.TypeDir:
			if err := os.MkdirAll(target, 0755); err != nil {
				return err
			}
		case tar.TypeReg:
			if err := os.MkdirAll(filepath.Dir(target), 0755); err != nil {
				return err
			}
			out, err := os.OpenFile(target, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, os.FileMode(hdr.Mode))

View on GitHub (pinned to a0bd20f762)

Solutions

1. Re-download the archive and verify its checksum against the index-provided hash
2. Test the archive manually (tar -tzf archive.tar.gz) to confirm it is intact
3. Remove any cached/partial artifact before rebuilding
4. Use a different mirror or the official PyPI index
5. If archives are custom-built, verify the packing tool produces standard ustar/pax tar output

Example fix

// before
extractTarGz(archiveFile, destDir)

// after: validate archive integrity first
cmd := exec.Command("tar", "-tzf", archiveFile)
if err := cmd.Run(); err != nil {
    os.Remove(archiveFile)
    return fmt.Errorf("archive %s is corrupt, re-downloading", archiveFile)
}
extractTarGz(archiveFile, destDir)

cmd := exec.Command("tar", "-tzf", archiveFile)
cmd.Stdout = io.Discard
if err := cmd.Run(); err != nil {
    return fmt.Errorf("archive %s failed integrity check: %w", archiveFile, err)
}

if err := extractTarGz(archiveFile, destDir); err != nil {
    if strings.Contains(err.Error(), "failed to read tar entry") {
        os.Remove(archiveFile) // truncated/corrupt tar: refetch
        return retryDownloadAndExtract()
    }
    return err
}

When it happens

Trigger: tr.Next() hits the end of a truncated gzip stream (unexpected EOF), the tar headers are malformed (header check-sum mismatch), or an underlying file read error occurs while streaming the archive.

Common situations: A download was interrupted at, say, 90% and cached; a mirror serves a cut-off archive; disk I/O failure while streaming; an archive produced by a non-standard tool with unusual header formats.

Related errors

• failed to process archive %s: %w
• failed to extract archive: %w
• failed to create gzip reader: %w
• failed to extract wheel: %w
• invalid archive name format: %s

AI-assisted analysis of anomalyco/sst@a0bd20f762 (2026-08-30). Data as JSON: /api/errors/6fca3baada0732b0. Report an issue: GitHub.