{"record":{"id":"06781095c530b10d","repo":"golang/go","slug":"errheader","errorCode":"ErrHeader","errorMessage":"archive/tar: invalid tar header","messagePattern":"archive/tar: invalid tar header","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/archive/tar/common.go","lineNumber":34,"sourceCode":"\t\"internal/godebug\"\n\t\"io/fs\"\n\t\"maps\"\n\t\"math\"\n\t\"path\"\n\t\"reflect\"\n\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)","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/archive/tar/common.go#L16-L52","documentation":"ErrHeader is the generic archive/tar sentinel for any malformed, truncated, or inconsistent tar header. The reader returns it from many sites: bad header checksum, unknown format flag, unparseable octal/hex numeric field, integer overflow in size/mtime, missing zero-block terminator, or a truncated stream mid-header. strconv.go also returns it for numeric parse failures. It signals the archive cannot be trusted as a tar.","triggerScenarios":"Calling Reader.Next() or reader.Read() on a file that is not a tar archive (gzip header, random bytes, partial download); a tar truncated mid-header; a header whose checksum field does not match the computed value; an octal numeric field with non-octal digits or value exceeding the field width; PAX/GNU extended header that fails validation.","commonSituations":"Decompressing a non-tar blob with the tar reader; reading a tar over HTTP where the connection dropped; corrupted tar from a flaky network/filesystem; tar produced by a buggy or very old tool with non-standard header encoding; downloading a tarball as text mode (CRLF mangling).","solutions":["Verify the file is actually a tar before reading: check magic at offset 257 (\"ustar\") or wrap with a sniffing reader.","Re-download or re-create the archive from a trusted source; compare checksums (sha256) to detect corruption.","If reading over HTTP, ensure the response is fully buffered and not truncated; check Content-Length vs actual bytes.","Open the tar with binary mode only (no CRLF translation) — on Windows use os.Open, not text-mode readers.","Switch to a more lenient reader or pre-validate with `tar -tvf file.tar` to localize the corruption."],"exampleFix":"// before\ntr := tar.NewReader(file)\nfor {\n  hdr, err := tr.Next() // throws ErrHeader on corrupt archive\n  ...\n}\n\n// after\nbuf := make([]byte, 512)\nn, _ := io.ReadFull(file, buf)\nfile.Seek(0, io.SeekStart)\nif n < 265 || string(buf[257:262]) != \"ustar\" {\n  return fmt.Errorf(\"not a tar archive (bad magic)\")\n}\ntr := tar.NewReader(file)","handlingStrategy":"try-catch","validationCode":"buf := make([]byte, 512)\nif n, _ := io.ReadFull(r, buf); n < 265 || string(buf[257:262]) != \"ustar\" {\n  return errors.New(\"not a tar archive\")\n}\nr.Seek(0, io.SeekStart)","typeGuard":"func isTarMagic(b []byte) bool { return len(b) >= 265 && string(b[257:262]) == \"ustar\" }","tryCatchPattern":"for {\n  hdr, err := tr.Next()\n  switch {\n  case errors.Is(err, io.EOF):\n    return nil\n  case errors.Is(err, tar.ErrHeader):\n    log.Printf(\"skipping corrupt entry: %v\", err)\n    continue\n  case err != nil:\n    return err\n  }\n  // process hdr\n}","preventionTips":["Verify the tar magic bytes before opening the tar reader.","Compare sha256 of downloaded archives against published checksums.","Open files in binary mode (no CRLF translation) on Windows.","Validate Content-Length vs bytes received for HTTP-fetched tars."],"tags":["archive-tar","validation","corruption","reader","header"],"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}