golang/go · error

ErrFieldTooLong

ErrFieldTooLong

Error message

archive/tar: header field too long

What it means

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.

Source

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

	"maps"
	"math"
	"path"
	"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)
		}
	}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Leave Header.Format unset (or set to FormatPAX) so long names spill into PAX extended headers automatically.
2. Do not force FormatUSTAR when names exceed 100 bytes; switch to FormatPAX or FormatGNU.
3. Shorten Name to a relative path (strip leading directories) before WriteHeader.
4. When reading, validate the producer is emitting compliant PAX; if necessary pre-truncate or skip the offending entry.

Example fix

// before
hdr := &tar.Header{Name: strings.Repeat("a", 200), Size: 0, Format: tar.FormatUSTAR}
tw.WriteHeader(hdr) // throws ErrFieldTooLong

// after
hdr := &tar.Header{Name: strings.Repeat("a", 200), Size: 0, Format: tar.FormatPAX}
tw.WriteHeader(hdr)

if len(hdr.Name) > 100 && (hdr.Format == tar.FormatUnknown || hdr.Format == tar.FormatUSTAR) {
  hdr.Format = tar.FormatPAX // allow long names via PAX
}

if err := tw.WriteHeader(hdr); errors.Is(err, tar.ErrFieldTooLong) {
  hdr.Format = tar.FormatPAX
  err = tw.WriteHeader(hdr)
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• ErrHeader
• ErrWriteTooLong
• ErrWriteAfterClose
• errMissData
• errUnrefData

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