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

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

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.