golang/go · error

archive/tar: unknown file mode %v

Error message

archive/tar: unknown file mode %v

What it means

Returned by tar.FileInfoHeader (common.go:679) as the default case when the os.FileInfo mode bits do not match any recognized type: regular file, dir, symlink, device (char/block), fifo, or socket. It signals a mode bit combination the tar package cannot map to a USTAR type flag.

Source

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

		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:
		if fm&fs.ModeCharDevice != 0 {
			h.Typeflag = TypeChar
		} else {
			h.Typeflag = TypeBlock
		}
	case fm&fs.ModeNamedPipe != 0:
		h.Typeflag = TypeFifo
	case fm&fs.ModeSocket != 0:
		return nil, fmt.Errorf("archive/tar: sockets not supported")
	default:
		return nil, fmt.Errorf("archive/tar: unknown file mode %v", fm)
	}
	if fm&fs.ModeSetuid != 0 {
		h.Mode |= c_ISUID
	}
	if fm&fs.ModeSetgid != 0 {
		h.Mode |= c_ISGID
	}
	if fm&fs.ModeSticky != 0 {
		h.Mode |= c_ISVTX
	}
	// If possible, populate additional fields from OS-specific
	// FileInfo fields.
	if sys, ok := fi.Sys().(*Header); ok {
		// This FileInfo came from a Header (not the OS). Use the
		// original Header to populate all remaining fields.
		h.Uid = sys.Uid
		h.Gid = sys.Gid
		h.Uname = sys.Uname

View on GitHub (pinned to b6b368adc5)

Solutions

1. Inspect the offending mode value printed in the error to see which bits are set.
2. Pre-classify entries: map unknown types to TypeReg or skip them before calling FileInfoHeader.
3. If walking a real unix tree, ensure you use os.Stat (not Lstat-with-odd-results) so type bits are populated.
4. On Windows/Plan9, convert reparse/special files to a representable type or omit them.

Example fix

// before
h, err := tar.FileInfoHeader(info, link) // unknown file mode %v

// after
mode := info.Mode()
switch {
case mode.IsRegular():
    h, err = tar.FileInfoHeader(info, link)
case mode&fs.ModeIrregular != 0:
    h, err = tar.FileInfoHeader SyntheticRegular(info) // or skip
default:
    h, err = tar.FileInfoHeader(info, link)
}

func archivableMode(m fs.FileMode) bool {
    switch {
    case m.IsRegular(), m.IsDir():
        return true
    case m&fs.ModeSymlink != 0,
         m&fs.ModeDevice != 0,
         m&fs.ModeNamedPipe != 0,
         m&fs.ModeSocket != 0:
        return true
    }
    return false
}

When it happens

Trigger: Passing an FileInfo whose mode is the zero value (no type bits set), or an irregular/typed file from a non-unix filesystem (e.g., Windows reparse points, Plan 9 special files) where ModeType bits are unset or unexpected.

Common situations: Archiving files reported by a custom/fs.FS that returns plain modes without a type bit; Windows files without ModeDir/ModeSymlink set; synthetic FileInfo from tests; filesystems reporting ModeIrregular only.

Related errors

• archive/tar: sockets not supported
• archive/tar: missed writing %d bytes
• file larger than size reported by stat
• copying %s to %s: %v
• file is empty

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