Go exclude Directive - Fix "excluded by exclude directive" in CI

An exclude directive in go.mod tells the module resolver to skip a specific version. It only removes that one version from consideration - it does not pin or cap a module - so it can either break resolution (the only available version is excluded) or appear ineffective (a different bad version is still selected).

What this error means

A build fails because a needed version is excluded by exclude directive in go.mod, or an exclude you added did not stop a problematic version because module-version selection still chose another release. The behavior is deterministic and tied to the go.mod directives.

go: github.com/org/lib@v1.5.0: excluded by exclude directive in go.mod
# or: the exclude is ignored because MVS selects v1.6.0 instead
go: selected github.com/org/lib v1.6.0 despite exclude of v1.5.0

Common causes

The only resolvable version is excluded

An exclude github.com/org/lib v1.5.0 removes the one version that satisfied the graph, so resolution has nothing left to select.

Exclude misused as a version cap

exclude only skips the named version. Excluding v1.5.0 does not stop v1.6.0 from being selected, so a single exclude rarely keeps a whole range out.

How to fix it

Pin the version you want instead of excluding

To force a specific version, require (or replace) it rather than excluding everything else.

go get github.com/org/lib@v1.4.0
go mod tidy

Drop an exclude that breaks resolution

If an exclude removes the only usable version, remove it and constrain the version another way.

go mod edit -dropexclude github.com/org/lib@v1.5.0
go mod tidy

How to prevent it

• Use exclude only to skip a single known-bad version, not as a cap.
• Pin versions with require/replace, not by excluding alternatives.
• Re-tidy after editing exclude so the selected versions are explicit.

Related guides