What causes "cannot embed irregular file %s" in golang/go?

Remove the irregular file from the package directory (e.g. `rm` the socket/FIFO).

cannot embed irregular file %s

Error message

cannot embed irregular file %s

What it means

In the switch at line 2225 over the matched file's mode, the default branch fires when info.Mode() is neither regular, nor (with GODEBUG embedfollowsymlinks=1) a symlink, nor a directory. That covers irregular files: device files, named pipes, sockets, etc. go:embed only embeds regular file contents.

Source

Thrown at src/cmd/go/internal/load/pkg.go:2226

				}
				if dir != file {
					if info, err := fsys.Lstat(dir); err == nil && !info.IsDir() {
						return nil, nil, fmt.Errorf("cannot embed %s %s: in non-directory %s", what, rel, dir[len(pkgdir)+1:])
					}
				}
				dirOK[dir] = true
				if elem := filepath.Base(dir); isBadEmbedName(elem) {
					if dir == file {
						return nil, nil, fmt.Errorf("cannot embed %s %s: invalid name %s", what, rel, elem)
					} else {
						return nil, nil, fmt.Errorf("cannot embed %s %s: in invalid directory %s", what, rel, elem)
					}
				}
			}

			switch {
			default:
				return nil, nil, fmt.Errorf("cannot embed irregular file %s", rel)

			case info.Mode().IsRegular():
				if have[rel] != pid {
					have[rel] = pid
					list = append(list, rel)
				}

			// If the embedfollowsymlinks GODEBUG is set to 1, allow the leaf file to be a
			// symlink (#59924). We don't allow directories to be symlinks and have already
			// checked that none of the parent directories of the file are symlinks in the
			// loop above. The file pointed to by the symlink must be a regular file.
			case embedfollowsymlinks.Value() == "1" && info.Mode()&fs.ModeType == fs.ModeSymlink:
				info, err := fsys.Stat(file)
				if err != nil {
					return nil, nil, err
				}
				if !info.Mode().IsRegular() {
					return nil, nil, fmt.Errorf("cannot embed irregular file %s", rel)

View on GitHub (pinned to b6b368adc5)

Solutions

Remove the irregular file from the package directory (e.g. `rm` the socket/FIFO).
Narrow the //go:embed glob to specific file extensions so it cannot match the irregular file.
Move the irregular file outside the embedded directory.

Example fix

// before: //go:embed data/*  and data/cli.sock is a socket
// after: rm data/cli.sock  OR narrow to
//go:embed data/*.json

Defensive patterns

Strategy: validation

Validate before calling

// Verify each embed target is a regular file before building.
package embedcheck

import (
	"errors"
	"os"
)

func EmbedTargetIsRegular(path string) error {
	info, err := os.Lstat(path)
	if err != nil {
		return err
	}
	if !info.Mode().IsRegular() {
		return errors.New("refusing to embed non-regular file: " + path)
	}
	return nil
}

Prevention

Keep sockets, FIFOs, and device files out of package directories.
Scope embed patterns to specific extensions (`//go:embed data/*.json`) rather than `data/*`.

When it happens

Trigger: An embed glob matches a FIFO, a Unix domain socket, a character/block device, or any non-regular non-directory non-symlink file. The glob can match it because Glob only filters by name, not by type.

Common situations: A leftover FIFO/socket created by a dev tool in the package directory; a /dev entry accidentally captured by a wide glob; build artifacts that are pipes used for IPC during tests.

Related errors

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