The go.sum file is failing verification because a dependency’s cryptographic hash doesn’t match what’s expected, indicating that the downloaded module code has been tampered with or is not the version you intended to use.
Here’s how to diagnose and fix go.sum hash verification errors, ordered by likelihood:
1. Corrupted Local Module Cache
The most frequent culprit is a corrupted entry in Go’s local module cache. Go downloads modules to a central cache ($GOPATH/pkg/mod or $HOME/go/pkg/mod) and uses hashes to ensure integrity. If a download was interrupted or a file got damaged, the hash check will fail.
Diagnosis:
Run go clean -modcache. This command will delete the entire local module cache. Go will then re-download all dependencies from scratch the next time you build or run a command.
Fix:
Execute go clean -modcache in your terminal.
Why it works: This forces Go to discard all cached modules and download fresh copies, resolving any corruption in the local cache.
2. Unexpected Module Version Change (Remote Source)
A dependency’s source code repository might have been altered, or a new version tagged that has a different hash. This is less common for stable releases but can happen with development branches or if a repository is compromised.
Diagnosis: Inspect the specific module path and version reported in the error message. Then, check the remote repository (e.g., GitHub) for that module and version. Look for any recent commits or tag changes that might have altered the code. You can also try to manually download the module and compute its hash:
go mod download example.com/some/module@v1.2.3
shasum -a 256 $HOME/go/pkg/mod/example.com/some/module/@v/v1.2.3.zip
Compare the output hash with the one in your go.sum file.
Fix:
If the remote source has legitimately changed and you want to accept the new version, run go get -u example.com/some/module@v1.2.3 or simply rebuild your project. Go will update go.sum with the new hash. If you don’t want the new version, you need to ensure your go.mod file specifies the exact version you expect, and then potentially remove the incorrect entry from go.sum (with caution, see below).
Why it works: go get -u explicitly tells Go to fetch the latest (or specified) version and update go.sum accordingly. If you want a specific older version, ensuring go.mod points to it and then cleaning the cache (go clean -modcache) will force Go to use that specific, known-good version.
3. Local go.mod File Mismatch
Your go.mod file might be specifying a version that doesn’t align with what’s in go.sum, or you might have manually edited go.sum incorrectly.
Diagnosis:
Open your go.mod file and compare the listed module versions with the problematic entries in your go.sum file. The version in go.mod should have a corresponding hash in go.sum.
Fix:
If your go.mod is correct, run go mod tidy. This command synchronizes your go.mod and go.sum files, adding missing entries and removing unused ones, while also verifying existing ones. If go.mod itself has an incorrect version, edit it to the desired version and then run go mod tidy.
Why it works: go mod tidy is designed to reconcile these two files. It will fetch the module specified in go.mod, verify its hash, and update go.sum if necessary.
4. Network Proxy or Firewall Interference
A misconfigured network proxy or an overly aggressive firewall can intercept and alter downloaded module content, leading to hash mismatches.
Diagnosis:
Try building or fetching modules from a different network environment if possible. If the error disappears, your network is the likely cause. Check your HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables.
Fix:
Configure your proxy settings correctly, or temporarily disable your firewall/VPN to test. Ensure your proxy is not attempting to cache or modify compressed module archives (.zip files). You might need to bypass the proxy for your Go module fetches.
Why it works: By ensuring the module download is not being tampered with in transit, Go receives the authentic, unaltered module archive, allowing the hash verification to succeed.
5. Git Tag Tampering or Re-tagging
If a module uses Git tags for versioning, and those tags have been altered (e.g., force-pushed over), it can cause go.sum mismatches. Go’s module system relies on the immutability of tagged versions.
Diagnosis:
Examine the Git history of the module’s repository, specifically around the version tag that’s causing issues. Look for any signs of force-pushing or tag re-creation. You can use git log --tags on a local clone of the repository.
Fix:
If the tag was legitimately re-created with different content, you’ll need to update your go.mod to reflect the new tag that points to the desired content, and then run go mod tidy. If it’s an accidental or malicious re-tag, you might need to specify a different, stable version in your go.mod or contact the module maintainer.
Why it works: Go trusts the tag associated with a module version. If the tag has been moved or its target changed, Go needs to be explicitly told about the new, correct tag (version) to use.
6. Manual go.sum Editing Gone Wrong
Occasionally, developers might manually edit go.sum to resolve minor issues or in specific advanced scenarios. If done incorrectly, it will break hash verification.
Diagnosis:
Compare the line in go.sum causing the error with the actual module and version it purports to represent. You can often find the correct hash by running go mod download example.com/some/module@v1.2.3 and then checking the downloaded zip file’s hash as described in point 2.
Fix:
The safest fix is to remove the incorrect line from go.sum and run go mod tidy. If the module is still required, go mod tidy will re-fetch it and add the correct hash. Only edit go.sum directly if you are absolutely certain you know the correct hash for the exact module version.
Why it works: go mod tidy will correct go.sum by re-downloading the required module version and recording its authentic hash, overwriting any incorrect manual entry.
After resolving these issues, you’ll likely encounter a "module signed by an unknown key" error if you’ve been using Go’s experimental module signing features and the signing key hasn’t been added to your trust store.