{"record":{"id":"094779e9a021630c","repo":"golang/go","slug":"error-reading-module-index-v","errorCode":null,"errorMessage":"error reading module index: %v","messagePattern":"error reading module index: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/modindex/read.go","lineNumber":283,"sourceCode":"//\tdefer unprotect(protect, &err)\n//\n// end looks for panics due to errCorrupt or bad mmap accesses.\n// When it finds them, it adds explanatory text, consumes the panic, and sets *errp instead.\n// If errp is nil, end adds the explanatory text but then calls base.Fatalf.\nfunc unprotect(old bool, errp *error) {\n\t// SetPanicOnFault's errors _may_ satisfy this interface. Even though it's not guaranteed\n\t// that all its errors satisfy this interface, we'll only check for these errors so that\n\t// we don't suppress panics that could have been produced from other sources.\n\ttype addrer interface {\n\t\tAddr() uintptr\n\t}\n\n\tdebug.SetPanicOnFault(old)\n\n\tif e := recover(); e != nil {\n\t\tif _, ok := e.(addrer); ok || e == errCorrupt {\n\t\t\t// This panic was almost certainly caused by SetPanicOnFault or our panic(errCorrupt).\n\t\t\terr := fmt.Errorf(\"error reading module index: %v\", e)\n\t\t\tif errp != nil {\n\t\t\t\t*errp = err\n\t\t\t\treturn\n\t\t\t}\n\t\t\tif isTest {\n\t\t\t\tpanic(err)\n\t\t\t}\n\t\t\tbase.Fatalf(\"%v\", err)\n\t\t}\n\t\t// The panic was likely not caused by SetPanicOnFault.\n\t\tpanic(e)\n\t}\n}\n\n// fromBytes returns a *Module given the encoded representation.\nfunc fromBytes(moddir string, data []byte) (m *Module, err error) {\n\tif !enabled {\n\t\tpanic(\"use of index\")","sourceCodeStart":265,"sourceCodeEnd":301,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/modindex/read.go#L265-L301","documentation":"Recovery error from unprotect() after a panic during large-scale module-index access. It fires only when the recovered value satisfies the addrer interface (a SetPanicOnFault memory-access fault) OR equals the errCorrupt sentinel — i.e. the on-disk index is unreadable or structurally invalid. The wrapped %v is the panic value. If errp is nil the message is passed to base.Fatalf; in tests it is re-panicked.","triggerScenarios":"Any index read wrapped by protect()/unprotect() (e.g. fromBytes) when the mmap'd index file is truncated, partially overwritten, or accessed past its end. SetPanicOnFault turns the bad memory access into a recoverable panic that unprotect converts into this error.","commonSituations":"GOMODCACHE corrupted by a killed `go mod download`, concurrent writers racing the index, disk full mid-write, third-party tools mutating files under the cache, or an OS-level mmap fault on a network filesystem.","solutions":["Clear the module cache and let Go rebuild it: `go clean -modcache`.","Re-run the failing command — `go mod download` regenerates the index.","If on a network filesystem, move GOMODCACHE to a local disk.","Verify disk health / free space; check dmesg for filesystem errors."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Defensive wrapper: if the index read fails, fall back to the live filesystem.\nfunc importWithFallback(modroot, dir string) (*build.Package, error) {\n    if pkg, err := modindex.OpenPackage(modroot, dir); err == nil {\n        return pkg, nil\n    }\n    // index unreadable — recompute directly\n    return build.ImportDir(filepath.Join(modroot, dir), 0)\n}","typeGuard":null,"tryCatchPattern":"// Treat index-read errors as recoverable: clear cache once and retry.\npkg, err := modindex.OpenPackage(modroot, dir)\nif err != nil && strings.Contains(err.Error(), \"error reading module index\") {\n    _ = os.RemoveAll(filepath.Join(os.Getenv(\"GOMODCACHE\"), \"cache/download\"))\n    pkg, err = modindex.OpenPackage(modroot, dir)\n}\nreturn pkg, err","preventionTips":["Do not share GOMODCACHE across Go toolchain major versions.","Add `go clean -modcache` to CI on cache-provider rotation.","Monitor disk health where the module cache lives."],"tags":["module-index","cache","corruption","io"],"backgroundTag":null,"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}