golang/go · error

reading overlay: %v

Error message

reading overlay: %v

What it means

Returned by fsys.Init when the -overlay flag points at a file that os.ReadFile cannot open. The overlay system needs to read that JSON file before any source file operation can honour the overlay, so a missing/unreadable overlay file fails fast at init.

Source

Thrown at src/cmd/go/internal/fsys/fsys.go:356

		}
	}
}

// Init initializes the overlay, if one is being used.
func Init() error {
	if overlay != nil {
		// already initialized
		return nil
	}

	if OverlayFile == "" {
		return nil
	}

	Trace("ReadFile", OverlayFile)
	b, err := os.ReadFile(OverlayFile)
	if err != nil {
		return fmt.Errorf("reading overlay: %v", err)
	}
	return initFromJSON(b)
}

func initFromJSON(js []byte) error {
	var ojs overlayJSON
	if err := json.Unmarshal(js, &ojs); err != nil {
		return fmt.Errorf("parsing overlay JSON: %v", err)
	}

	seen := make(map[string]string)
	var list []replace
	for _, from := range slices.Sorted(maps.Keys(ojs.Replace)) {
		if from == "" {
			return fmt.Errorf("empty string key in overlay map")
		}
		afrom := abs(from)
		if old, ok := seen[afrom]; ok {

View on GitHub (pinned to b6b368adc5)

Solutions

1. Check the path exists and is readable: `ls -l` the file you passed to -overlay.
2. Use an absolute path for -overlay to avoid working-directory ambiguity.
3. Confirm the file is a regular file, not a directory.
4. Verify read permissions for the user running the go command.

Example fix

# before
$ go build -overlay=overlay.json ./...
error: reading overlay: open overlay.json: no such file or directory
# after — absolute, verified path
$ go build -overlay="$PWD/overlay.json" ./...

import (
    "os"
    "path/filepath"
)

func resolveOverlay(p string) (string, error) {
    if p == "" { return "", nil }
    abs, err := filepath.Abs(p)
    if err != nil { return "", err }
    info, err := os.Stat(abs)
    if err != nil { return "", fmt.Errorf("overlay file unreadable: %w", err) }
    if info.IsDir() { return "", fmt.Errorf("overlay path is a directory: %s", abs) }
    return abs, nil
}

When it happens

Trigger: Invoking `go build -overlay=missing.json ./...`, pointing -overlay at a path that does not exist, has wrong permissions, or is a directory.

Common situations: Typos in the -overlay path; relative paths resolved against the wrong working directory; permissions/ownership issues; CI runners checking out only part of the repo that omits the overlay file.

Related errors

• duplicate paths %s and %s in overlay map
• parsing overlay JSON: %v
• empty string key in overlay map
• deleted in overlay
• cannot open directory in overlay

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