What is in the Go module cache (GOMODCACHE), and when is go clean -modcache the right fix?

## What lives in the module cache `GOMODCACHE` names one directory, defaulting to `$GOPATH/pkg/mod`, shared by every Go module on the machine. Inside it are two distinct things: 1. **Extracted module trees**, under paths that encode the module path and version, e.g. `.../golang.org/x/[email protected]/`. These are the sources the compiler actually reads. 2. **A download store**, under `cache/download`, holding the raw files as fetched from the module source — the `.info`, `.mod` and `.zip` for each version, plus the recorded hashes and lock files. Its layout mirrors the module proxy protocol, which is why the directory can itself be served as a proxy: pointing GOPROXY at it with a `file://` URL gives you a completely offline module source built from what a machine has already downloaded. The practical consequence of one machine-wide cache is that a first build in a fresh container is slow and every build after it is fast — and that CI systems cache this directory between runs, which is where most of its failure modes come from. ## Why the files are read-only Extracted module files are created without write permission. This is not paranoia about attackers; it is about a specific, very costly accident: a quick edit to a dependency "just to test something" would silently apply to every build on that machine, would not appear in any diff, and would vanish the moment the cache was cleared. The build would be unreproducible in a way nobody could see. Read-only turns that mistake into an immediate error. The permissions also mean the directory cannot be deleted with a naive recursive remove without fighting the mode bits — which is precisely why `go clean -modcache` exists rather than an instruction to delete the folder. (A `-modcacherw` build flag makes newly written cache files writable, for the rare tooling that needs it; it is a deliberate trade, not a default.) ## Two checks that are easy to confuse - **`go mod verify`** re-hashes what is already extracted in the cache and compares against `go.sum`. It is offline and answers a narrow question: *has anything on this machine changed since it was downloaded?* A modified file, a truncated extraction, a tool that rewrote something. - **Download-time verification** happens on every fetch: the go command hashes what it received and compares it against `go.sum` (consulting the checksum database when there is no recorded line yet). This answers: *is the content I just received the content everyone expects?* Both compare against `go.sum`. Neither compares against the cache as an authority — the cache is never the source of truth. ## When `go clean -modcache` is right It removes the entire cache, so the next build downloads and verifies everything again. Reach for it when the evidence points at **local state**: - a download killed part-way, leaving a partially written zip or a half-extracted tree; - a CI cache archive that was saved while a build was still writing, then restored on a later run; - a machine where several toolchains or containers have been writing to the same shared path; - `go mod verify` reporting a specific module as changed on one machine while every other machine is fine. It is heavy — the next build re-downloads everything — so on CI it is a targeted intervention, and if it becomes a routine step in the pipeline, the real bug is in how the cache is saved and restored, not in the modules. ## When it is not the fix A `go.sum` mismatch is the case people most often reach for it, and it does not help. Verification is against the recorded hash, so a clean re-download produces the same mismatch. What the clean cache *does* buy you is a clean answer to one triage question: **is this local or not?** If the mismatch survives a fresh download on a fresh machine, the local cache was never involved, and the question moves to what was published and what `go.sum` records — a security-review conversation, not a cache one. The destructive responses to resist in the meantime are all attempts to make the tooling stop complaining: deleting the go.sum line, running a command that rewrites it, or setting the go command to write module files instead of reading them read-only. Each of them converts a loud, precise failure into a green build with an unanswered question behind it. When an organisation-wide build failure starts at the same minute everywhere, the fact that it *is* everywhere is the most useful thing you know: the same recorded hash and the same downloaded content on every machine means the divergence is upstream, and the first thing to preserve is the exact error text and the module version it names.