golang/go · error

archive/tar: sockets not supported

Error message

archive/tar: sockets not supported

What it means

Returned by tar.FileInfoHeader (common.go:677) when the os.FileInfo reports fs.ModeSocket in its mode bits. The USTAR/PAX format has no type flag for sockets, so the archive writer refuses to create a header for one rather than emitting a corrupt or misleading entry.

Source

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

	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:
		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

View on GitHub (pinned to b6b368adc5)

Solutions

1. Skip sockets during traversal: check `info.Mode()&fs.ModeSocket != 0` in your WalkFunc and return nil.
2. Filter by file type before calling FileInfoHeader: only archive regular files, dirs, symlinks, fifos, devices.
3. If you must represent a socket, substitute a placeholder regular file or omit it and log.

Example fix

// before
err := filepath.Walk(root, func(p string, info fs.FileInfo, err error) error {
    h, err := tar.FileInfoHeader(info, "") // fails on sockets
    ...
})

// after
err := filepath.Walk(root, func(p string, info fs.FileInfo, err error) error {
    if info.Mode()&fs.ModeSocket != 0 {
        return nil // skip sockets
    }
    h, err := tar.FileInfoHeader(info, "")
    ...
})

func isSocket(info fs.FileInfo) bool {
    return info.Mode()&fs.ModeSocket != 0
}

When it happens

Trigger: Calling tar.FileInfoHeader (or Writer.WriteHeader with a header derived from FileInfo) on a unix domain socket file: os.Stat on a /path/to/socket.sock returns ModeSocket, and the tar header builder rejects it.

Common situations: Walking a filesystem tree that contains unix sockets (e.g., /var/run, container runtime dirs, /tmp) and archiving everything; backing up a directory holding database/runtime sockets; recursive tar of a Docker/containerd state dir.

Related errors

• archive/tar: unknown file mode %v
• 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/9f41376019f701c1. Report an issue: GitHub.