errMissData

errMissData

Error message

archive/tar: sparse file references non-existent data

What it means

errMissData (unexported) is returned by the sparse-file reader and writer when the sparse map declares holes that reference byte ranges beyond the file's total Size, i.e. the dense data stream does not provide enough bytes to fill the declared data fragments. It indicates an internally inconsistent sparse entry.

Source

Thrown at src/archive/tar/common.go:39

	"reflect"
	"strconv"
	"strings"
	"time"
)

// BUG: Use of the Uid and Gid fields in Header could overflow on 32-bit
// architectures. If a large value is encountered when decoding, the result
// stored in Header will be the truncated version.

var tarinsecurepath = godebug.New("tarinsecurepath")

var (
	ErrHeader          = errors.New("archive/tar: invalid tar header")
	ErrWriteTooLong    = errors.New("archive/tar: write too long")
	ErrFieldTooLong    = errors.New("archive/tar: header field too long")
	ErrWriteAfterClose = errors.New("archive/tar: write after close")
	ErrInsecurePath    = errors.New("archive/tar: insecure file path")
	errMissData        = errors.New("archive/tar: sparse file references non-existent data")
	errUnrefData       = errors.New("archive/tar: sparse file contains unreferenced data")
	errWriteHole       = errors.New("archive/tar: write non-NUL byte in sparse hole")
	errSparseTooLong   = errors.New("archive/tar: sparse map too long")
)

type headerError []string

func (he headerError) Error() string {
	const prefix = "archive/tar: cannot encode header"
	var ss []string
	for _, s := range he {
		if s != "" {
			ss = append(ss, s)
		}
	}
	if len(ss) == 0 {
		return prefix
	}

View on GitHub (pinned to b6b368adc5)

Solutions

Re-acquire the archive from a trusted source and verify its checksum.
When constructing sparse headers, ensure sum(sparseDataFragments) == Header.Size and that you write exactly that many bytes.
Skip or quarantine the entry on errMissData rather than retrying — the format is internally inconsistent.
If reading untrusted archives, treat any unexported tar error as corruption and log the entry name for triage.

Example fix

// before
hdr := &tar.Header{
  Size:  10,
  Sparses: []tar.SparseEntry{{Offset: 0, NumBytes: 20}}, // mismatch
}
tw.WriteHeader(hdr)
tw.Write(make([]byte, 10)) // throws errMissData

// after
hdr := &tar.Header{
  Size:  20,
  Sparses: []tar.SparseEntry{{Offset: 0, NumBytes: 20}},
}
tw.WriteHeader(hdr)
tw.Write(make([]byte, 20))

Defensive patterns

Strategy: validation

Validate before calling

var sum int64
for _, s := range hdr.Sparses { sum += s.NumBytes }
if sum != hdr.Size {
  return fmt.Errorf("sparse fragments sum %d != Size %d", sum, hdr.Size)
}

Try / catch

if _, err := tr.Read(buf); errors.Is(err, tar.errMissData) || strings.Contains(err.Error(), "sparse file references non-existent data") {
  log.Printf("corrupt sparse entry %q; skipping", hdr.Name)
  continue
}

Prevention

When authoring sparse entries, ensure sum(sparse fragments) == Header.Size.
Verify checksums of untrusted archives before extraction.
Quarantine entries that fail sparse consistency checks rather than retrying.

When it happens

Trigger: Reading a sparse tar entry whose sparse map's data fragments sum to more than Header.Size (the dense data is shorter than the map requires); writing a sparse entry where the caller-provided data is shorter than the sum of the sparse data fragments declared.

Common situations: Corrupted sparse archive from a faulty producer; truncated download of a sparse tar; manually constructed Header with a sparse map that disagrees with Size or with the bytes actually written.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/a03ce0e25abb6206. Report an issue: GitHub.