{"record":{"id":"28d5d8a824fe0f11","repo":"golang/go","slug":"inconsistent-files-s-and-s-in-overlay-map","errorCode":null,"errorMessage":"inconsistent files %s and %s in overlay map","messagePattern":"inconsistent files (.+?) and (.+?) in overlay map","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/fsys/fsys.go","lineNumber":395,"sourceCode":"\t\tseen[afrom] = from\n\t\tlist = append(list, replace{from: afrom, to: abs(ojs.Replace[from])})\n\t}\n\n\tslices.SortFunc(list, func(x, y replace) int { return cmp(x.from, y.from) })\n\n\tfor i, r := range list {\n\t\tif r.to == \"\" { // deleted\n\t\t\tcontinue\n\t\t}\n\t\t// have file for r.from; look for child file implying r.from is a directory\n\t\tprefix := r.from + string(filepath.Separator)\n\t\tfor _, next := range list[i+1:] {\n\t\t\tif !strings.HasPrefix(next.from, prefix) {\n\t\t\t\tbreak\n\t\t\t}\n\t\t\tif next.to != \"\" {\n\t\t\t\t// found child file\n\t\t\t\treturn fmt.Errorf(\"inconsistent files %s and %s in overlay map\", r.from, next.from)\n\t\t\t}\n\t\t}\n\t}\n\n\toverlay = list\n\treturn nil\n}\n\n// IsDir returns true if path is a directory on disk or in the\n// overlay.\nfunc IsDir(path string) (bool, error) {\n\tTrace(\"IsDir\", path)\n\n\tswitch info := stat(path); {\n\tcase info.dir:\n\t\treturn true, nil\n\tcase info.deleted, info.replaced:\n\t\treturn false, nil","sourceCodeStart":377,"sourceCodeEnd":413,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/fsys/fsys.go#L377-L413","documentation":"The Go overlay filesystem (enabled via -overlay flag pointing to a JSON file) maps virtual paths to real files. This error fires during overlay initialization when a path is mapped as a file (has a non-empty 'to' target) while simultaneously having a child path also mapped as a file, implying the parent is a directory. A single path cannot be both a file and a directory, so the overlay is rejected as internally inconsistent.","triggerScenarios":"Passing -overlay=overlay.json where the Replace map contains both '/proj/foo.go' -> '/real/foo.go' and '/proj/foo.go/bar.go' -> '/real/bar.go'. The first entry treats foo.go as a file; the second implies it is a directory containing bar.go. The sorted-path scan in initFromJSON detects this parent/child conflict.","commonSituations":"Hand-editing overlay JSON files for test harnesses or IDE integration. Automated overlay generators that don't validate parent/child relationships. Copying overlay entries between different directory layouts where a path changes from directory to file. Mistakenly replacing a path that should be a directory with a file mapping.","solutions":["Inspect the two paths named in the error — the parent is treated as both a file and a directory in the overlay JSON.","If the parent should be a file, remove child entries that place files beneath it (e.g., delete the '/proj/foo.go/bar.go' entry).","If the parent should be a directory, ensure the parent entry itself is not mapped to a file target — either remove it or mark it as deleted (empty 'to').","Regenerate the overlay JSON from scratch, ensuring each replaced path is unambiguously a file or deleted."],"exampleFix":"// before — overlay JSON is inconsistent\n{\n  \"Replace\": {\n    \"/proj/main.go\": \"/real/main.go\",\n    \"/proj/main.go/util.go\": \"/real/util.go\"\n  }\n}\n// after — main.go is a file only\n{\n  \"Replace\": {\n    \"/proj/main.go\": \"/real/main.go\"\n  }\n}","handlingStrategy":"validation","validationCode":"// Validate overlay JSON for parent/child file conflicts before use.\nfunc validateOverlay(entries map[string]string) error {\n    var paths []string\n    for from, to := range entries {\n        if to != \"\" {\n            paths = append(paths, from)\n        }\n    }\n    sort.Strings(paths)\n    for i, a := range paths {\n        prefix := a + string(filepath.Separator)\n        for _, b := range paths[i+1:] {\n            if !strings.HasPrefix(b, prefix) {\n                break\n            }\n            return fmt.Errorf(\"inconsistent overlay: %s is both file and parent of %s\", a, b)\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate the overlay JSON structure before passing it to -overlay.","Use a test harness that checks overlay consistency on load.","Generate overlay maps programmatically rather than hand-editing."],"tags":["go","go-toolchain","overlay","fsys","configuration"],"backgroundTag":null,"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}