{"record":{"id":"942b12eeecee0cdd","repo":"golang/go","slug":"deleted-in-overlay","errorCode":null,"errorMessage":"deleted in overlay","messagePattern":"deleted in overlay","errorType":"exception","errorClass":"fs.PathError","httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/fsys/fsys.go","lineNumber":564,"sourceCode":"\treturn \"\", false\n}\n\n// Open opens the named file in the virtual file system.\n// It must be an ordinary file, not a directory.\nfunc Open(name string) (*os.File, error) {\n\tTrace(\"Open\", name)\n\n\tbad := func(msg string) (*os.File, error) {\n\t\treturn nil, &fs.PathError{\n\t\t\tOp:   \"Open\",\n\t\t\tPath: name,\n\t\t\tErr:  errors.New(msg),\n\t\t}\n\t}\n\n\tinfo := stat(name)\n\tif info.deleted {\n\t\treturn bad(\"deleted in overlay\")\n\t}\n\tif info.dir {\n\t\treturn bad(\"cannot open directory in overlay\")\n\t}\n\tif info.replaced {\n\t\tname = info.actual\n\t}\n\n\treturn os.Open(name)\n}\n\n// ReadFile reads the named file from the virtual file system\n// and returns the contents.\nfunc ReadFile(name string) ([]byte, error) {\n\tf, err := Open(name)\n\tif err != nil {\n\t\treturn nil, err\n\t}","sourceCodeStart":546,"sourceCodeEnd":582,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/fsys/fsys.go#L546-L582","documentation":"The Go overlay filesystem (activated with the -overlay flag) allows certain files to be marked as deleted via a JSON configuration file. When Open() is called on such a path, the internal stat() function returns info.deleted=true and Open returns an fs.PathError with 'deleted in overlay'. This is the overlay mechanism's intentional way of representing files that should appear removed from the virtual source tree.","triggerScenarios":"OverlayFS.Open(name) calls stat(name) which checks the overlay JSON configuration. The path is listed in the overlay's Replace or Delete map as deleted, so info.deleted is true. Open returns a PathError wrapping this message.","commonSituations":"A -overlay JSON file explicitly marks the file as deleted for conditional builds; build tooling generates an overlay to remove files for specific build configurations; CI configuration uses overlays to simulate file removal; stale overlay config from a previous build that no longer applies.","solutions":["Inspect the overlay JSON file passed to -overlay for deleted entries matching the path","Remove or correct the overlay configuration if the file should not be deleted","Ensure the file exists on the real filesystem if the overlay deletion is stale","Pass -overlay='' (empty) to disable the overlay entirely if it's not needed","Regenerate the overlay configuration if it's produced by build tooling"],"exampleFix":"// before: overlay JSON marks file as deleted\n// overlay.json:\n// {\"Replace\": {}, \"Delete\": [\"src/main.go\"]}\n// $ go build -overlay=overlay.json ./...\n// # error: Open src/main.go: deleted in overlay\n\n// after: remove the deletion entry or disable overlay\n// overlay.json:\n// {\"Replace\": {}, \"Delete\": []}\n// $ go build -overlay=overlay.json ./...\n// or simply:\n// $ go build ./...","handlingStrategy":"validation","validationCode":"// Before building with an overlay, validate the overlay JSON for deleted paths.\nimport \"encoding/json\"\n\nfunc validateOverlay(overlayPath string, requiredFiles []string) error {\n    data, err := os.ReadFile(overlayPath)\n    if err != nil {\n        return err\n    }\n    var overlay struct {\n        Replace map[string]string `json:\"Replace\"`\n        Delete  []string          `json:\"Delete\"`\n    }\n    if err := json.Unmarshal(data, &overlay); err != nil {\n        return err\n    }\n    deletedSet := make(map[string]bool)\n    for _, p := range overlay.Delete {\n        deletedSet[p] = true\n    }\n    for _, f := range requiredFiles {\n        if deletedSet[f] {\n            return fmt.Errorf(\"overlay deletes required file: %s\", f)\n        }\n    }\n    return nil\n}","typeGuard":"// The error is returned as *fs.PathError with Op=\"Open\".\nimport \"io/fs\"\n\nfunc isOverlayDeleted(err error) bool {\n    var pathErr *fs.PathError\n    if errors.As(err, &pathErr) {\n        return pathErr.Op == \"Open\" && strings.Contains(pathErr.Err.Error(), \"deleted in overlay\")\n    }\n    return false\n}","tryCatchPattern":"// file, err := fsys.Open(path)\n// if err != nil {\n//     if isOverlayDeleted(err) {\n//         // The file is intentionally deleted in the overlay.\n//         // Handle the absence or adjust the overlay config.\n//         return nil, fmt.Errorf(\"required file %s is deleted in overlay\", path)\n//     }\n//     return nil, err\n// }","preventionTips":["Review the overlay JSON file before builds to ensure no required files are accidentally deleted","Regenerate overlay configs from source when project structure changes","Use version control for overlay configs to track changes","Pass -overlay='' when no overlay is needed to avoid stale configs","Document which files are intentionally deleted in overlays and why"],"tags":["go","overlay","filesystem","virtual-fs"],"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T11:17:21.771Z"}