Go "missing go.sum entry" - Fix Incomplete go.sum in CI

By Daniel Zoghalchali·Latchkey

A build needs a module whose hash is not in go.sum. With network access off (the CI default for verified builds), Go refuses to fetch and record it on the fly, so the missing entry is a hard failure.

What this error means

A go build or go test stops with missing go.sum entry for module providing package ... and a hint to run go mod download or go mod tidy. It typically appears right after adding an import or bumping a dependency without re-tidying.

missing go.sum entry for module providing package
github.com/example/lib/v2 (imported by app/main.go);
to add:
	go mod download github.com/example/lib/v2

Diagnose it: module path, proxy, or checksum?

Go module errors name the module but rarely the layer that failed. Separate the three: the module path does not resolve, the proxy cannot serve it, or the checksum database disagrees with what was downloaded.

# what Go resolves and from where
go env GOPROXY GOSUMDB GOPRIVATE GOFLAGS

# does the module resolve at all, bypassing the build?
go list -m -versions github.com/org/module

# verify the module cache against go.sum
go mod verify

# private modules must be excluded from proxy and sumdb
go env -w GOPRIVATE=github.com/yourorg/*

Common causes

go.sum not regenerated after a dependency change

A new import or version bump added a requirement that go.sum has no hash for, because go mod tidy was not run before committing.

go.sum not committed or partially committed

If go.sum is gitignored or a merge dropped lines, CI checks out an incomplete file and cannot verify the missing module.

How to fix it

Tidy and commit go.mod and go.sum

Re-resolve the full dependency graph so every required hash is recorded, then commit both files.

go mod tidy
git add go.mod go.sum
git commit -m "Update go.sum"

Add a single missing module

When only one module is missing, download it directly to record its hash.

go mod download github.com/example/lib/v2

Enforce tidiness in CI

Fail the build if a PR changed dependencies but forgot to tidy, so the gap is caught before merge.

go mod tidy
git diff --exit-code go.mod go.sum   # nonzero if not tidy

How to prevent it

• Run go mod tidy after every dependency change and commit the result.
• Commit go.sum; never gitignore it.
• Add a git diff --exit-code go.mod go.sum guard step to CI.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation