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

By Kaveh Alemi·Latchkey

Every module names itself in its go.mod module line. If you require it under a different path, Go rejects the mismatch instead of resolving it.

What this error means

A build fails with module declares its path as X but was required as Y. It usually means a fork is required under the original path, or a major-version suffix (/v2) is missing or wrong.

go: github.com/yourorg/lib@v1.0.0: parsing go.mod:
	module declares its path as: github.com/upstream/lib
	but was required as: github.com/yourorg/lib

Common causes

Fork required under the original path

You required your fork by your own org path, but its go.mod still declares the upstream module path.

Missing or wrong major-version suffix

A v2+ module must declare and be imported with a /v2 suffix; omitting it produces a path mismatch.

How to fix it

Use a replace for forks

1. Require the upstream path and redirect it to your fork with a replace directive.
2. Or update the fork go.mod module line to your org path and import that.

// go.mod
require github.com/upstream/lib v1.0.0
replace github.com/upstream/lib => github.com/yourorg/lib v1.0.0

Fix the major-version suffix

1. Ensure the module declares module .../v2 and you import .../v2.
2. Run go mod tidy after correcting the path.

go get github.com/foo/bar/v2@v2.1.0
go mod tidy

How to prevent it

• Keep import paths aligned with each module go.mod declaration.
• Always include the /vN suffix for major versions 2 and up.
• Use replace directives for forks instead of renaming requires.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation