{"record":{"id":"73047790aed6270b","repo":"golang/go","slug":"parsing-overlay-json-v","errorCode":null,"errorMessage":"parsing overlay JSON: %v","messagePattern":"parsing overlay JSON: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/fsys/fsys.go","lineNumber":364,"sourceCode":"\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 {\n\t\t\treturn fmt.Errorf(\"duplicate paths %s and %s in overlay map\", old, from)\n\t\t}\n\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","sourceCodeStart":346,"sourceCodeEnd":382,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/fsys/fsys.go#L346-L382","documentation":"Returned by fsys.initFromJSON when the overlay file is read successfully but its contents fail json.Unmarshal into overlayJSON. The overlay file must be a JSON document with the expected schema (a 'replace' map and optional 'other' map).","triggerScenarios":"Passing a non-JSON file to -overlay; JSON with syntax errors; a JSON document whose structure does not match overlayJSON (e.g. replace is an array instead of an object).","commonSituations":"Hand-edited JSON with trailing commas or comments; YAML or TOML mistakenly passed as overlay; merging overlays by concatenation producing invalid JSON; field type mismatches.","solutions":["Validate the file with `jq . overlay.json` (or `python -m json.tool`) to surface the syntax error.","Ensure the top-level object has 'replace' as an object mapping source path -> target path (and optionally 'other').","Remove JSON comments and trailing commas — strict JSON only.","Regenerate the overlay from whatever tool produced it if it has drifted."],"exampleFix":"// before — overlay.json with a trailing comma / comment\n{ \"replace\": { \"a.go\": \"b.go\", } /* fix */ }\n// after — strict JSON\n{ \"replace\": { \"a.go\": \"b.go\" } }","handlingStrategy":"validation","validationCode":"import \"encoding/json\"\n\nfunc validateOverlayJSON(path string) error {\n    b, err := os.ReadFile(path)\n    if err != nil { return err }\n    var ojs struct {\n        Replace map[string]string `json:\"replace\"`\n        Other   map[string]string `json:\"other\"`\n    }\n    if err := json.Unmarshal(b, &ojs); err != nil {\n        return fmt.Errorf(\"overlay JSON invalid: %w\", err)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `jq . overlay.json` before invoking go to catch syntax errors.","Generate overlays programmatically rather than hand-editing.","Use strict JSON — no comments, no trailing commas."],"tags":["overlay","json","validation","go-command"],"backgroundTag":null,"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}