Go "go mod why" Empty / "does not need" - Diagnose Dependencies in CI

go mod why explains which import chain pulls in a module. When it reports a module is not needed - yet go.mod still requires it, or a build fails without it - the import that needs it is usually behind a build tag or in a package go mod why did not consider.

What this error means

go mod why github.com/org/lib prints (main module does not need package ...) even though removing the require breaks a tagged or platform-specific build. The mismatch surfaces when go mod tidy drops a require that a -tags/GOOS-gated file actually uses.

$ go mod why github.com/org/lib
# github.com/org/lib
(main module does not need package github.com/org/lib)

# yet:
$ go build -tags integration ./...
no required module provides package github.com/org/lib

Common causes

The import is behind a build tag

A file gated by //go:build integration (or a specific GOOS) imports the module. Default go mod why/go mod tidy does not see that import, so the module looks unneeded.

Asking about the module, not the package actually used

go mod why -m and go mod why <package> answer different questions; querying the wrong target can show "not needed" while a subpackage is in use.

How to fix it

Tidy with the build tags your code uses

Include the tags so tidy and why account for tag-gated imports.

go mod tidy -e
GOFLAGS="-tags=integration" go mod tidy

Query the module graph directly

Trace who requires the module with the module-level form and the full graph.

go mod why -m github.com/org/lib
go mod graph | grep github.com/org/lib

How to prevent it

• Run go mod tidy with the same build tags your CI builds use.
• Use go mod why -m and go mod graph to confirm real dependents.
• Keep tag-gated imports in mind before dropping a "not needed" require.

Related guides