## TL;DR
A missing go.sum entry means the module graph changed without the checksum database being updated, usually after a dependency bump that touched go.mod but not go.sum. Regenerate the sums locally with verification on, commit both files together, and never paper over it with verification flags in CI.

```text
missing go.sum entry; to add it:
        go mod download [MODULE]@[VERSION]
```

## Steps

1. Reproduce the exact failure locally with the same Go version as CI:
```bash
go version
go build ./...
```
Expected: the same missing go.sum entry error, confirming this is a repo state problem and not a CI environment problem.

2. Regenerate the missing sums with checksum verification fully enabled:
```bash
go mod tidy
```
Expected: go.sum gains the missing entries and the command exits clean. `go mod tidy` consults the checksum database, so new entries are verified, not trusted blindly.

3. Verify the module graph is now consistent and reproducible:
```bash
go mod verify
go build ./...
```
Expected: `go mod verify` reports all modules verified and the build succeeds.

4. Commit go.mod and go.sum together:
```bash
git add go.mod go.sum
git commit -m "Update module checksums"
```
Expected: both files move in one commit, so the pipeline never sees a go.mod that references sums that are not there.

5. Confirm CI passes with verification enforced:
```bash
GOFLAGS=-mod=readonly GONOSUMCHECK= go build ./...
```
Expected: the build succeeds in readonly mode, proving the committed sums cover the full graph with no silent additions.

## When to use
- `go build` or `go mod download` fails in CI with missing go.sum entry
- A dependency bump PR updated go.mod but CI complains about go.sum
- You need the fix without weakening supply-chain verification

## When not to use
- The error names a checksum MISMATCH rather than a missing entry; that can indicate tampering and needs investigation before regenerating anything
- The failure is a proxy or network error reaching the module proxy; that is egress, not checksums
- You are vendoring; then the fix is refreshing the vendor tree, not go.sum

## Why it happens
go.mod records which module versions the build needs while go.sum records their verified hashes. Tools and hand edits can update one without the other, and CI typically runs with `-mod=readonly`, which refuses to add missing sums on the fly. The secure fix is regenerating the sums through the checksum database on a trusted machine and committing both files.

## Edge cases
- `GOFLAGS=-mod=mod` in CI hides the problem by silently updating go.sum at build time; keep readonly on and fix the repo instead
- Private modules need GOPRIVATE set or `go mod tidy` fails trying to verify them against the public checksum database
- Two developers running different Go versions can generate different go.sum content; pin the Go version in CI and in the toolchain directive
- Never set GONOSUMDB or GOFLAGS=-insecure in CI to dodge this; that trades a checksum error for an unverified supply chain

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CRt5wzW1iOvzjqYwu7CHpg