What causes "parsing overlay JSON: %v" in golang/go?

Validate the file with `jq . overlay.json` (or `python -m json.tool`) to surface the syntax error.

parsing overlay JSON: %v

Error message

parsing overlay JSON: %v

What it means

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).

Source

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

		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 {
			return fmt.Errorf("duplicate paths %s and %s in overlay map", old, from)
		}
		seen[afrom] = from
		list = append(list, replace{from: afrom, to: abs(ojs.Replace[from])})
	}

	slices.SortFunc(list, func(x, y replace) int { return cmp(x.from, y.from) })

View on GitHub (pinned to b6b368adc5)

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.

Example fix

// before — overlay.json with a trailing comma / comment
{ "replace": { "a.go": "b.go", } /* fix */ }
// after — strict JSON
{ "replace": { "a.go": "b.go" } }

Defensive patterns

Strategy: validation

Validate before calling

import "encoding/json"

func validateOverlayJSON(path string) error {
    b, err := os.ReadFile(path)
    if err != nil { return err }
    var ojs struct {
        Replace map[string]string `json:"replace"`
        Other   map[string]string `json:"other"`
    }
    if err := json.Unmarshal(b, &ojs); err != nil {
        return fmt.Errorf("overlay JSON invalid: %w", err)
    }
    return nil
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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