A build under the default -mod=readonly needs a module whose checksum is not recorded in go.sum. Go will not silently add it, so it stops.
What this error means
A build or test fails with missing go.sum entry for module providing package X; to add it: go mod download X. It usually means go.sum was not committed after a dependency change, or only a partial tidy was run.
go
missing go.sum entry for module providing package github.com/pkg/errors
(imported by example.com/app); to add it:
go mod download github.com/pkg/errors
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.
Terminal
# 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 updated after a new import
A package was imported or a dependency bumped without running go mod tidy, so its checksum was never written to go.sum.
Partial commit of module files
go.mod was committed but go.sum was left out (or vice versa), leaving the checksum file incomplete.
How to fix it
Tidy and commit go.sum
Run go mod tidy to reconcile go.mod and go.sum with the real import graph.
Commit both files together so the readonly build has every checksum it needs.
Terminal
go mod tidy
git add go.mod go.sum
git commit -m "go mod tidy"
Guard tidiness in CI
Run go mod tidy in the pipeline.
Fail if it changes go.mod or go.sum, flagging an uncommitted update.
.github/workflows/ci.yml
go mod tidygit diff --exit-code go.mod go.sum
How to prevent it
Run go mod tidy after every import or dependency change.
Always stage go.mod and go.sum together.
Add a git diff --exit-code go.mod go.sum guard to CI.
Frequently asked questions
What causes Go "missing go.sum entry for module"?
There are 2 common causes: go.sum not updated after a new import and partial commit of module files. A package was imported or a dependency bumped without running go mod tidy, so its checksum was never written to go.sum.
How do I fix Go "missing go.sum entry for module"?
There are 2 fixes depending on which cause you have: tidy and commit go.sum and guard tidiness in ci. Work through them in order, since the first is the most common.
What does Go "missing go.sum entry for module" actually mean?
A build or test fails with missing go.sum entry for module providing package X; to add it: go mod download X.
How do I stop Go "missing go.sum entry for module" happening again?
Run go mod tidy after every import or dependency change. The prevention section lists 3 changes that keep it from recurring.
