golang/go · error · DownloadDirPartialError

ziphash file is missing

Error message

ziphash file is missing

What it means

The .ziphash file records the hash of the module zip and must be written before extraction so integrity can be verified. If it does not exist (os.IsNotExist) while the directory and zip are present, DownloadDir returns a DownloadDirPartialError because the cache entry cannot be trusted without its hash.

Source

Thrown at src/cmd/go/internal/modfetch/cache.go:135

	// Special case: ziphash is not required for the golang.org/fips140 module,
	// because it is unpacked from a file in GOROOT, not downloaded.
	// We've already checked that it's not a partial unpacking, so we're happy.
	if m.Path == "golang.org/fips140" {
		return dir, nil
	}

	// Check if a .ziphash file exists. It should be created before the
	// zip is extracted, but if it was deleted (by another program?), we need
	// to re-calculate it. Note that checkMod will repopulate the ziphash
	// file if it doesn't exist, but if the module is excluded by checks
	// through GONOSUMDB or GOPRIVATE, that check and repopulation won't happen.
	ziphashPath, err := CachePath(ctx, m, "ziphash")
	if err != nil {
		return dir, err
	}
	if _, err := os.Stat(ziphashPath); os.IsNotExist(err) {
		return dir, &DownloadDirPartialError{dir, errors.New("ziphash file is missing")}
	} else if err != nil {
		return dir, err
	}
	return dir, nil
}

// DownloadDirPartialError is returned by DownloadDir if a module directory
// exists but was not completely populated.
//
// DownloadDirPartialError is equivalent to fs.ErrNotExist.
type DownloadDirPartialError struct {
	Dir string
	Err error
}

func (e *DownloadDirPartialError) Error() string     { return fmt.Sprintf("%s: %v", e.Dir, e.Err) }
func (e *DownloadDirPartialError) Is(err error) bool { return err == fs.ErrNotExist }

View on GitHub (pinned to b6b368adc5)

Solutions

1. Run `go clean -modcache` and re-download the module so the ziphash is regenerated.
2. Run `go mod verify` to surface affected modules, then re-download those specifically.
3. Avoid deleting individual metadata files inside GOMODCACHE; clean the whole cache if needed.

// Verify the ziphash exists before trusting a cached module:
//   if _, err := os.Stat(ziphashPath); os.IsNotExist(err) {
//     // re-download to regenerate the hash
//   }

// On DownloadDirPartialError("ziphash file is missing"),
// remove the cache entry and run `go mod download` to regenerate it.

When it happens

Trigger: The .ziphash file for a cached module is absent while the module directory exists, so the integrity check cannot run.

Common situations: The .ziphash was deleted manually or by an overzealous cleanup tool; the cache was populated by an old go version that did not write ziphash; GONOSUMDB/GOPRIVE skipping the check that would repopulate the hash.

Related errors

• bad checksum
• not a directory
• not completely extracted
• not in module index
• corrupt index

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