Go Checksum Database Errors - Fix sum.golang.org Failures in CI

Go verifies new module hashes against the public checksum database at sum.golang.org. When that lookup fails - a private module the sum DB cannot see, or a transient network error reaching it - the module cannot be added.

What this error means

A fetch fails with verifying <module>@<version>: <path>: reading https://sum.golang.org/...: 404 Not Found or a timeout. Public modules verify fine; the failure is on a private path or an intermittent network blip.

verifying github.com/yourorg/internal@v1.2.0/go.mod:
	github.com/yourorg/internal@v1.2.0/go.mod: reading
	https://sum.golang.org/lookup/github.com/yourorg/internal@v1.2.0: 404 Not Found

Common causes

A private module sent to the public sum DB

Without GONOSUMCHECK/GONOSUMDB/GOPRIVATE covering it, Go asks sum.golang.org to verify a private module it cannot see, and gets a 404.

Transient failure reaching the sum database

A brief network or DNS issue reaching sum.golang.org surfaces as a verification failure that clears on retry.

How to fix it

Exclude private modules from the sum database

Mark internal paths private so Go skips both the public proxy and the checksum database for them.

export GOPRIVATE=github.com/yourorg/*
# GOPRIVATE implies GONOSUMCHECK + GONOSUMDB for those paths
go mod download

Set GONOSUMDB / GONOSUMCHECK explicitly

When you need finer control than GOPRIVATE, name the paths to skip in the sum DB directly.

export GONOSUMDB=github.com/yourorg/*
export GOFLAGS=-mod=mod

Retry a transient sum-DB failure

A genuine 404 for a private path will not fix itself, but an intermittent network error reaching sum.golang.org usually clears on a second attempt.

How to prevent it

• Set GOPRIVATE for every internal module path.
• Keep GONOSUMDB/GONOSUMCHECK aligned with your private paths.
• Cache the module cache so sum-DB lookups happen less often.

Related guides