What causes "archive/tar: FileInfo is nil" in golang/go?

Always check the error from os.Stat/Lstat before using the FileInfo: if err != nil { return err }.

archive/tar: FileInfo is nil

Error message

archive/tar: FileInfo is nil

What it means

Returned by tar.FileInfoHeader when the fs.FileInfo argument is nil. FileInfoHeader reads fi.Name(), fi.Mode(), fi.Size(), etc., so a nil value would panic on the first method call; the explicit check returns a clean error instead. It is a programmer error, not a runtime/environmental condition.

Source

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

	c_ISBLK  = 060000  // Block special file
	c_ISCHR  = 020000  // Character special file
	c_ISSOCK = 0140000 // Socket
)

// FileInfoHeader creates a partially-populated [Header] from fi.
// If fi describes a symlink, FileInfoHeader records link as the link target.
// If fi describes a directory, a slash is appended to the name.
//
// Since fs.FileInfo's Name method only returns the base name of
// the file it describes, it may be necessary to modify Header.Name
// to provide the full path name of the file.
//
// If fi implements [FileInfoNames]
// Header.Gname and Header.Uname
// are provided by the methods of the interface.
func FileInfoHeader(fi fs.FileInfo, link string) (*Header, error) {
	if fi == nil {
		return nil, errors.New("archive/tar: FileInfo is nil")
	}
	fm := fi.Mode()
	h := &Header{
		Name:    fi.Name(),
		ModTime: fi.ModTime(),
		Mode:    int64(fm.Perm()), // or'd with c_IS* constants later
	}
	switch {
	case fm.IsRegular():
		h.Typeflag = TypeReg
		h.Size = fi.Size()
	case fi.IsDir():
		h.Typeflag = TypeDir
		h.Name += "/"
	case fm&fs.ModeSymlink != 0:
		h.Typeflag = TypeSymlink
		h.Linkname = link
	case fm&fs.ModeDevice != 0:

View on GitHub (pinned to b6b368adc5)

Solutions

Always check the error from os.Stat/Lstat before using the FileInfo: if err != nil { return err }.
Inside fs.WalkDir, propagate the walk error and skip entries where d == nil.
If the file may not exist, branch on os.IsNotExist(err) and decide explicitly rather than passing nil.

Example fix

// before
fi, _ := os.Stat(path) // error ignored, fi is nil
hdr, err := tar.FileInfoHeader(fi, "") // throws: FileInfo is nil

// after
fi, err := os.Stat(path)
if err != nil { return err }
hdr, err := tar.FileInfoHeader(fi, "")

Defensive patterns

Strategy: validation

Validate before calling

fi, err := os.Stat(path)
if err != nil { return err }
if fi == nil { return errors.New("internal: nil FileInfo for " + path) }
hdr, err := tar.FileInfoHeader(fi, "")

Type guard

func isFileInfo(v interface{}) bool { _, ok := v.(fs.FileInfo); return ok && v != nil }

Prevention

Always check the error from os.Stat/Lstat before using the FileInfo.
Inside fs.WalkDir, propagate the walk error; do not assume d.Info() succeeds.
Assert non-nil at the boundary where FileInfo enters your code.

When it happens

Trigger: Calling tar.FileInfoHeader(nil, "") because the caller passed a nil fs.FileInfo — typically the result of a failed os.Stat whose error was ignored, or a custom walk that returned nil for missing files.

Common situations: Ignoring the error from os.Stat/Lstat and passing the zero-value nil FileInfo into FileInfoHeader; buggy fs.WalkDir handler that loses the info object; mock/stub that returns nil FileInfo.

Related errors

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