The 2 AM Pipeline FailureYou’ve pushed your code, the local tests passed, and you’re ready to call it a night. Then, the CI/CD pipeline turns red. You check the logs and find this annoying blocker:
go: updates to go.sum needed, disabled by -mod=readonly
This error usually hits during Docker builds or CI runs. It means the Go toolchain needs to update your go.sum file with missing checksums, but it's restricted from making changes. Since Go 1.16, many commands default to -mod=readonly to ensure builds are immutable and reproducible.
Why it's happeningGo expects go.mod and go.sum to be perfectly in sync. If you add a dependency or manually edit go.mod without running a sync command, go.sum becomes outdated. In a local environment, Go might fix this silently. However, in a CI environment like GitHub Actions or GitLab CI, the filesystem is often treated as read-only for dependencies. This prevents "silent" updates that could compromise security or build stability.
How to Fix It### 1. The Definitive Fix: go mod tidyThe most common cause is a go.sum file missing entries for dependencies listed in go.mod. Open your terminal and run:
go mod tidy
This command is your best friend. It adds missing module requirements for your imports and removes unused ones. Most importantly, it generates the exact checksums your project needs and cleans up the module graph.
2. Don't Forget to CommitIt’s a common trap: you run go mod tidy, see it work locally, but forget to commit the updated go.sum file. Your CI runner only knows what is in the repository. If you don't push the changes, the CI will still see the old, broken state and fail the build again.
git add go.mod go.sum
git commit -m "fix: sync dependencies and update go.sum"
git push
3. Correcting Docker BuildsIf this error crops up during a RUN go build step in Docker, check your COPY commands. If you copy go.mod but omit go.sum, the Go builder will try to generate a new checksum file on the fly and fail. Use this pattern instead:
# Copy both module files first to leverage Docker layer caching
COPY go.mod go.sum ./
RUN go mod download
# Now copy the rest of your source code
COPY . .
RUN go build -o myapp .
This ensures all checksums are present and verified before the build starts. It also keeps your Docker builds fast by caching the download step.
4. Force a Fresh DownloadIf tidy doesn't solve it, you might have a checksum mismatch in your local cache. Try forcing a clean download of all modules to reconcile the state:
go mod download
go mod verify
The verify command checks that the dependencies in your local cache match the expected checksums in go.sum. If it passes locally but fails in CI, your local go.sum is definitely the problem.
Verify Before You PushStop guessing if the CI will pass. You can simulate the CI environment's strictness locally by running your build with the readonly flag enabled:
go build -mod=readonly ./...
If this command exits with code 0, your dependencies are perfectly synced. Your pipeline will be green.