What causes "not a regular file" in golang/go?

Ensure the embed path points to an actual regular file, not a device or pipe

not a regular file

Error message

not a regular file

What it means

When processing //go:embed directives, the compiler opens and stats each referenced file via fileStringSym. It checks info.Mode().IsRegular() to ensure the file is a regular file. This error fires when the path resolves to a device, named pipe, socket, or other non-regular file type.

Source

Thrown at src/cmd/compile/internal/staticdata/data.go:133

// fileStringSym returns a symbol for the contents and the size of file.
// If readonly is true, the symbol shares storage with any literal string
// or other file with the same content and is placed in a read-only section.
// If readonly is false, the symbol is a read-write copy separate from any other,
// for use as the backing store of a []byte.
// The content hash of file is copied into hashBytes. (If hash is nil, nothing is copied.)
// The returned symbol contains the data itself, not a string header.
func fileStringSym(pos src.XPos, file string, readonly bool, hashBytes []byte) (*obj.LSym, int64, error) {
	f, err := os.Open(file)
	if err != nil {
		return nil, 0, err
	}
	defer f.Close()
	info, err := f.Stat()
	if err != nil {
		return nil, 0, err
	}
	if !info.Mode().IsRegular() {
		return nil, 0, fmt.Errorf("not a regular file")
	}
	size := info.Size()
	if size <= 1*1024 {
		data, err := io.ReadAll(f)
		if err != nil {
			return nil, 0, err
		}
		if int64(len(data)) != size {
			return nil, 0, fmt.Errorf("file changed between reads")
		}
		var sym *obj.LSym
		if readonly {
			sym = StringSym(pos, string(data))
		} else {
			sym = slicedata(pos, string(data))
		}
		if len(hashBytes) > 0 {
			sum := hash.Sum32(data)

View on GitHub (pinned to b6b368adc5)

Solutions

Ensure the embed path points to an actual regular file, not a device or pipe
Remove or exclude symlinks that point to special files from the embed directory
Check for accidental embed of system paths: verify each file with 'file' or 'stat' command
If using embed.FS with directory patterns, exclude directories containing special files

Defensive patterns

Strategy: validation

Validate before calling

// Verify that embed targets are regular files before building
import (
    "os"
    "path/filepath"
)

func validateEmbedTargets(dir string) error {
    return filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {
        if err != nil {
            return err
        }
        if !info.IsDir() && !info.Mode().IsRegular() {
            return fmt.Errorf("%s is not a regular file (mode: %v)", path, info.Mode())
        }
        return nil
    })
}

Prevention

Check embed directories for special files (pipes, sockets, devices) before building
Remove symlinks pointing to non-regular files from embed directories
Avoid embedding from /dev, /proc, /sys, or other virtual filesystems
Use a clean assets directory for embed targets

When it happens

Trigger: An //go:embed directive that references a named pipe (mkfifo), device file (/dev/null, /dev/urandom), Unix domain socket, or other special file. Broken symlinks that resolve to special files.

Common situations: Accidentally embedding system files from /dev, /proc, or /sys. Build environments where FIFO pipes are used for inter-process communication and accidentally matched by embed patterns. Symlinks in the embed directory pointing to devices.

Related errors

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