golang/go · error

corrupt single-package index

Error message

corrupt single-package index

What it means

Returned by packageFromBytes when the encoded index blob parsed successfully (fromBytes did not return errCorrupt) but the package count field m.n is not exactly 1. packageFromBytes is the single-package accessor and is only valid on blobs that index exactly one package; any other count means the file is logically corrupt for this API.

Source

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

		return nil, errCorrupt
	}

	m = &Module{
		moddir,
		d,
		n,
	}
	return m, nil
}

// packageFromBytes returns a *IndexPackage given the encoded representation.
func packageFromBytes(modroot string, data []byte) (p *IndexPackage, err error) {
	m, err := fromBytes(modroot, data)
	if err != nil {
		return nil, err
	}
	if m.n != 1 {
		return nil, fmt.Errorf("corrupt single-package index")
	}
	return m.pkg(0), nil
}

// pkgDir returns the dir string of the i'th package in the index.
func (m *Module) pkgDir(i int) string {
	if i < 0 || i >= m.n {
		panic(errCorrupt)
	}
	return m.d.stringAt(12 + 8 + 8*i)
}

// pkgOff returns the offset of the data for the i'th package in the index.
func (m *Module) pkgOff(i int) int {
	if i < 0 || i >= m.n {
		panic(errCorrupt)
	}
	return m.d.intAt(12 + 8 + 8*i + 4)

View on GitHub (pinned to b6b368adc5)

Solutions

  1. Delete the affected module's index entry: `go clean -modcache`.
  2. Re-download the module: `go mod download <module>`.
  3. Ensure the same Go toolchain version writes and reads the cache (avoid mixing toolchain versions against one GOMODCACHE).
Defensive patterns

Strategy: fallback

Validate before calling

// Prefer Module.Walk / Module.Package instead of packageFromBytes for arbitrary blobs.
// If you must read a single-package blob, validate the count first.
func safeSinglePackage(modroot string, data []byte) (*modindex.IndexPackage, error) {
    m, err := modindex.FromBytes(modroot, data)
    if err != nil { return nil, err }
    // (illustrative — Module.n is internal; this mirrors the runtime check)
    return m.Package(".") // returns a not-found style error rather than corrupt-single-package
}

Try / catch

// packageFromBytes errors are fatal-cache; refresh and retry once.
pkg, err := modindex.PackageFromBytes(modroot, data)
if err != nil && strings.Contains(err.Error(), "corrupt single-package index") {
    _ = os.Remove(indexPath)
    data, _ = os.ReadFile(regenerateIndex(modroot))
    pkg, err = modindex.PackageFromBytes(modroot, data)
}

Prevention

When it happens

Trigger: Calling packageFromBytes on a multi-package index file or a zero-package file. Indicates a mismatch between the caller's expectation and the index writer, or a corrupt cache entry that fromBytes did not structurally catch.

Common situations: Index file partially regenerated, version skew between a `go` binary that wrote the index and one that reads it, or third-party tampering with the cache.

Related errors

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