golang/go · error

corrupt index

Error message

corrupt index

What it means

The module index file is malformed or unreadable: packageFromBytes or the surrounding fault-protected read failed. protect() enables debug.SetPanicOnFault and the recover translates a fault or parse failure into errCorrupt ("corrupt index"), indicating the on-disk index cannot be trusted.

Source

Thrown at src/cmd/go/internal/modindex/read.go:247

			// But double check on Windows that we haven't opened the file yet,
			// because once mmap opens the file, we can't close it, and
			// Windows won't let us open an already opened file.
			data = indexPackage(modroot, pkgdir)
			if runtime.GOOS != "windows" || !opened {
				if err = cache.PutBytes(cache.Default(), id, data); err != nil {
					return nil, err
				}
			}
		}
		pkg, err := packageFromBytes(modroot, data)
		if err != nil {
			return nil, err
		}
		return pkg, nil
	})
}

var errCorrupt = errors.New("corrupt index")

// protect marks the start of a large section of code that accesses the index.
// It should be used as:
//
//	defer unprotect(protect, &err)
//
// It should not be used for trivial accesses which would be
// dwarfed by the overhead of the defer.
func protect() bool {
	return debug.SetPanicOnFault(true)
}

var isTest = false

// unprotect marks the end of a large section of code that accesses the index.
// It should be used as:
//
//	defer unprotect(protect, &err)

View on GitHub (pinned to b6b368adc5)

Solutions

  1. Run `go clean -modcache` to delete the cache and let the index rebuild cleanly.
  2. Ensure all toolchains sharing the cache are at compatible go versions.
  3. If corruption recurs, verify disk health and that GOMODCACHE is not on an unreliable network/overlay filesystem.
Defensive patterns

Strategy: fallback

Try / catch

// On errors.Is(err, errCorrupt) (or the "corrupt index" message),
// run `go clean -modcache` and retry; the index rebuilds on next use.

Prevention

When it happens

Trigger: Reading the index file triggers a SIGSEGV (unmapped page) recovered by protect(), or the bytes fail to parse into an IndexPackage via packageFromBytes.

Common situations: Disk corruption; an index write interrupted by a crash or kill; partially-cloned GOMODCACHE; mismatched go versions writing incompatible index formats to a shared cache; truncated file from ENOSPC during write.

Related errors

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