Go "module declares its path as X but was required as Y" - Fix in CI

Go fetched a module and found that its own go.mod declares a different module path than the one your require (or replace) used. A module’s declared path must match how it is imported, or Go refuses it.

What this error means

A build fails with module declares its path as: github.com/org/lib but was required as: github.com/org/lib/v2 (or a fork path). The fetch succeeds but the declared identity disagrees with the requirement.

go: github.com/org/lib@v2.0.0: parsing go.mod:
	module declares its path as: github.com/org/lib
	        but was required as: github.com/org/lib/v2

Common causes

A v2+ module without the version suffix in its go.mod

A /v2+ module must declare module .../v2 in its own go.mod. If upstream tagged v2 without updating the module line, requiring it as /v2 mismatches.

A replace pointing at a fork with a different module line

A replace redirects an import to a fork whose go.mod still declares the original (or another) path, so the declared and required paths disagree.

How to fix it

Match the version suffix to the declared path

1. Check the dependency’s go.mod module line at the tag you require.
2. If it lacks the /vN suffix, require the version it actually declares, or pin a tag where the module line is correct.
3. Report the missing major-version suffix upstream if it is their bug.

Align a replace with the fork’s real module path

When redirecting to a fork, make the replace target’s module path match what your code imports.

// in your fork's go.mod, declare the path your build expects
module github.com/org/lib
// then, in the consumer:
// replace github.com/org/lib => github.com/yourfork/lib v1.4.1-patch

How to prevent it

• For v2+ modules, ensure the go.mod module line carries the /vN suffix.
• Make replace targets declare the same module path you import.
• Pin tags whose go.mod module line is correct.

Related guides