{"record":{"id":"b9b2940b9498e220","repo":"golang/go","slug":"reading-overlay-v","errorCode":null,"errorMessage":"reading overlay: %v","messagePattern":"reading overlay: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/fsys/fsys.go","lineNumber":356,"sourceCode":"\t\t}\n\t}\n}\n\n// Init initializes the overlay, if one is being used.\nfunc Init() error {\n\tif overlay != nil {\n\t\t// already initialized\n\t\treturn nil\n\t}\n\n\tif OverlayFile == \"\" {\n\t\treturn nil\n\t}\n\n\tTrace(\"ReadFile\", OverlayFile)\n\tb, err := os.ReadFile(OverlayFile)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"reading overlay: %v\", err)\n\t}\n\treturn initFromJSON(b)\n}\n\nfunc initFromJSON(js []byte) error {\n\tvar ojs overlayJSON\n\tif err := json.Unmarshal(js, &ojs); err != nil {\n\t\treturn fmt.Errorf(\"parsing overlay JSON: %v\", err)\n\t}\n\n\tseen := make(map[string]string)\n\tvar list []replace\n\tfor _, from := range slices.Sorted(maps.Keys(ojs.Replace)) {\n\t\tif from == \"\" {\n\t\t\treturn fmt.Errorf(\"empty string key in overlay map\")\n\t\t}\n\t\tafrom := abs(from)\n\t\tif old, ok := seen[afrom]; ok {","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/fsys/fsys.go#L338-L374","documentation":"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.","triggerScenarios":"Invoking `go build -overlay=missing.json ./...`, pointing -overlay at a path that does not exist, has wrong permissions, or is a directory.","commonSituations":"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.","solutions":["Check the path exists and is readable: `ls -l` the file you passed to -overlay.","Use an absolute path for -overlay to avoid working-directory ambiguity.","Confirm the file is a regular file, not a directory.","Verify read permissions for the user running the go command."],"exampleFix":"# before\n$ go build -overlay=overlay.json ./...\nerror: reading overlay: open overlay.json: no such file or directory\n# after — absolute, verified path\n$ go build -overlay=\"$PWD/overlay.json\" ./...","handlingStrategy":"validation","validationCode":"import (\n    \"os\"\n    \"path/filepath\"\n)\n\nfunc resolveOverlay(p string) (string, error) {\n    if p == \"\" { return \"\", nil }\n    abs, err := filepath.Abs(p)\n    if err != nil { return \"\", err }\n    info, err := os.Stat(abs)\n    if err != nil { return \"\", fmt.Errorf(\"overlay file unreadable: %w\", err) }\n    if info.IsDir() { return \"\", fmt.Errorf(\"overlay path is a directory: %s\", abs) }\n    return abs, nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass -overlay an absolute path.","Stat the file before invoking go to produce a clearer error.","Check the file into the repo so CI can read it."],"tags":["overlay","filesystem","build-flag","validation","go-command"],"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T08:17:17.861Z"}