Go "go mod tidy" Failures in CI - Diagnose tidy Errors

By Kaveh Alemi·Latchkey

go mod tidy walks every import and reconciles go.mod/go.sum with the real dependency graph. It fails when an import cannot be resolved, a dependency cannot be fetched, or - in a verify step - the committed files are not tidy.

What this error means

A go mod tidy step errors while loading a package, or a build prints updates to go.mod needed; to update it: go mod tidy. The module graph and the committed files disagree.

go output

go: updates to go.mod needed; to update it:
	go mod tidy

# or, during tidy itself:
go: finding module for package github.com/example/gone
go: app imports github.com/example/gone: module ... : reading ...: 404 Not Found

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

Committed go.mod/go.sum are not tidy

Someone added or removed an import without running tidy, so the build (or a -mod=readonly step) reports that updates are needed.

An import cannot be resolved

tidy fails to find a module for an import - a deleted package, a wrong path, or a version that no longer exists upstream.

A dependency cannot be fetched during tidy

A private module without credentials, or a proxy 404/410, makes tidy fail because it cannot load the full graph.

How to fix it

Tidy locally and commit the result

Terminal

go mod tidy
git add go.mod go.sum
git commit -m "go mod tidy"

Resolve the unresolvable import

Read which import path tidy cannot find.
Fix the path, drop the dead import, or pin a version that still exists.
For private modules, set GOPRIVATE and credentials before tidying.

Verify tidiness in CI without mutating files

Run tidy, then fail if it changed anything - catching un-tidied PRs.

.github/workflows/ci.yml

go mod tidy
git diff --exit-code go.mod go.sum

How to prevent it

Run go mod tidy after every import or dependency change.
Build with -mod=readonly in CI so drift fails fast.
Pin existing versions and configure private-module access.

Frequently asked questions

What causes Go "go mod tidy" failures in CI?

There are 3 common causes: committed go.mod/go.sum are not tidy, an import cannot be resolved, and a dependency cannot be fetched during tidy. Someone added or removed an import without running tidy, so the build (or a -mod=readonly step) reports that updates are needed.

How do I fix Go "go mod tidy" failures in CI?

There are 3 fixes depending on which cause you have: tidy locally and commit the result, resolve the unresolvable import, and verify tidiness in ci without mutating files. Work through them in order, since the first is the most common.

What does Go "go mod tidy" failures in CI actually mean?

A go mod tidy step errors while loading a package, or a build prints updates to go.mod needed; to update it: go mod tidy.

How do I stop Go "go mod tidy" failures in CI happening again?

Run go mod tidy after every import or dependency change. The prevention section lists 3 changes that keep it from recurring.