{"record":{"id":"30a8fb8dfbb92625","repo":"golang/go","slug":"errunrefdata","errorCode":"errUnrefData","errorMessage":"archive/tar: sparse file contains unreferenced data","messagePattern":"archive/tar: sparse file contains unreferenced data","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/archive/tar/common.go","lineNumber":40,"sourceCode":"\t\"strconv\"\n\t\"strings\"\n\t\"time\"\n)\n\n// BUG: Use of the Uid and Gid fields in Header could overflow on 32-bit\n// architectures. If a large value is encountered when decoding, the result\n// stored in Header will be the truncated version.\n\nvar tarinsecurepath = godebug.New(\"tarinsecurepath\")\n\nvar (\n\tErrHeader          = errors.New(\"archive/tar: invalid tar header\")\n\tErrWriteTooLong    = errors.New(\"archive/tar: write too long\")\n\tErrFieldTooLong    = errors.New(\"archive/tar: header field too long\")\n\tErrWriteAfterClose = errors.New(\"archive/tar: write after close\")\n\tErrInsecurePath    = errors.New(\"archive/tar: insecure file path\")\n\terrMissData        = errors.New(\"archive/tar: sparse file references non-existent data\")\n\terrUnrefData       = errors.New(\"archive/tar: sparse file contains unreferenced data\")\n\terrWriteHole       = errors.New(\"archive/tar: write non-NUL byte in sparse hole\")\n\terrSparseTooLong   = errors.New(\"archive/tar: sparse map too long\")\n)\n\ntype headerError []string\n\nfunc (he headerError) Error() string {\n\tconst prefix = \"archive/tar: cannot encode header\"\n\tvar ss []string\n\tfor _, s := range he {\n\t\tif s != \"\" {\n\t\t\tss = append(ss, s)\n\t\t}\n\t}\n\tif len(ss) == 0 {\n\t\treturn prefix\n\t}\n\treturn fmt.Sprintf(\"%s: %v\", prefix, strings.Join(ss, \"; and \"))","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/archive/tar/common.go#L22-L58","documentation":"errUnrefData (unexported) is returned when the dense data stream contains MORE bytes than the sparse map references — i.e. there are bytes in the stream that no sparse data fragment covers, so they would be silently dropped. Like errMissData it signals an internally inconsistent sparse entry and is returned by both the reader and writer paths.","triggerScenarios":"Reading a sparse tar entry whose dense data length exceeds the sum of sparse data fragments; writing a sparse entry where the bytes pushed exceed the sum of declared fragment lengths (extra trailing bytes).","commonSituations":"Corrupted sparse archive; truncated or extended download; hand-built sparse Header whose Sparses array underestimates the data to be written.","solutions":["Re-fetch the archive and validate checksum.","When writing sparse entries, ensure the total bytes you push equals sum(sparse fragments) and matches Header.Size minus the hole regions.","Quarantine the entry on errUnrefData; do not retry — the sparse map and data disagree.","For untrusted input, log and skip rather than attempting repair."],"exampleFix":"// before\nhdr := &tar.Header{\n  Size: 20,\n  Sparses: []tar.SparseEntry{{Offset: 0, NumBytes: 5}}, // under-declared\ntw.WriteHeader(hdr)\ntw.Write(make([]byte, 20)) // throws errUnrefData\n\n// after\nhdr := &tar.Header{\n  Size: 20,\n  Sparses: []tar.SparseEntry{{Offset: 0, NumBytes: 20}},\n}\ntw.WriteHeader(hdr)\ntw.Write(make([]byte, 20))","handlingStrategy":"validation","validationCode":"var sum int64\nfor _, s := range hdr.Sparses { sum += s.NumBytes }\nif sum != hdr.Size {\n  return fmt.Errorf(\"sparse fragments sum %d != Size %d (unref data risk)\", sum, hdr.Size)\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"sparse file contains unreferenced data\") {\n  log.Printf(\"corrupt sparse entry %q; skipping\", hdr.Name)\n  continue\n}","preventionTips":["Match the bytes you write to the sum of sparse data fragments exactly.","Validate sparse archives from untrusted sources via checksum before extraction.","Treat any unexported tar sparse error as corruption and skip the entry."],"tags":["archive-tar","sparse","validation","corruption","reader","writer"],"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}