{"record":{"id":"4fe4e662b79a39f6","repo":"golang/go","slug":"errfieldtoolong","errorCode":"ErrFieldTooLong","errorMessage":"archive/tar: header field too long","messagePattern":"archive/tar: header field too long","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/archive/tar/common.go","lineNumber":36,"sourceCode":"\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)\n\t\t}\n\t}","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/archive/tar/common.go#L18-L54","documentation":"ErrFieldTooLong is returned when a tar header field exceeds the maximum allowed encoded size. For the writer, this happens when a name, linkname, uname, gname, or PAX/GNU extension field cannot fit in the 512-byte block (or the maxSpecialFileSize cap for PAX/GNU records); for the reader, when an extended header record is larger than maxSpecialFileSize. It indicates the header content is too large for the chosen format.","triggerScenarios":"Calling WriteHeader with a Name longer than 100 bytes without PAX/GNU support, or longer than the USTAR prefix/suffix split allows; setting Uname/Gname strings exceeding their field widths when Format is set to FormatUSTAR; an extended (x/L) header in the input stream exceeding maxSpecialFileSize (512 bytes by default).","commonSituations":"Archiving files with very long absolute paths on Windows or deeply nested paths; forcing FormatUSTAR for compatibility but providing names that need PAX; reader encountering a PAX record from a buggy producer that emits oversized records.","solutions":["Leave Header.Format unset (or set to FormatPAX) so long names spill into PAX extended headers automatically.","Do not force FormatUSTAR when names exceed 100 bytes; switch to FormatPAX or FormatGNU.","Shorten Name to a relative path (strip leading directories) before WriteHeader.","When reading, validate the producer is emitting compliant PAX; if necessary pre-truncate or skip the offending entry."],"exampleFix":"// before\nhdr := &tar.Header{Name: strings.Repeat(\"a\", 200), Size: 0, Format: tar.FormatUSTAR}\ntw.WriteHeader(hdr) // throws ErrFieldTooLong\n\n// after\nhdr := &tar.Header{Name: strings.Repeat(\"a\", 200), Size: 0, Format: tar.FormatPAX}\ntw.WriteHeader(hdr)","handlingStrategy":"validation","validationCode":"if len(hdr.Name) > 100 && (hdr.Format == tar.FormatUnknown || hdr.Format == tar.FormatUSTAR) {\n  hdr.Format = tar.FormatPAX // allow long names via PAX\n}","typeGuard":null,"tryCatchPattern":"if err := tw.WriteHeader(hdr); errors.Is(err, tar.ErrFieldTooLong) {\n  hdr.Format = tar.FormatPAX\n  err = tw.WriteHeader(hdr)\n}","preventionTips":["Default to FormatPAX when names may exceed 100 bytes.","Strip leading directories from Name to keep it relative and short.","Do not force FormatUSTAR for paths you do not control."],"tags":["archive-tar","writer","header","format","path-length"],"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T08:17:17.861Z"}