Go "replace ... => ... vX.Y.Z" Version Errors - Fix in CI

A replace old => new vX.Y.Z redirects a module to a fork or alternate module at a specific version. When that version does not exist on the replacement, or the version string is malformed, Go rejects the replace before building.

What this error means

A build fails resolving a versioned replace, with replacement github.com/fork/lib@v1.2.3: invalid version: unknown revision or replace ...: version "v1.2" invalid: must be of the form v1.2.3. The original module resolves fine; only the replacement version fails.

go output

go: github.com/org/app/go.mod:
	replace github.com/org/lib => github.com/fork/lib v1.4.9:
	invalid version: unknown revision v1.4.9

Common causes

The replacement version does not exist on the fork

A replace => github.com/fork/lib v1.4.9 pins a tag the fork never published, so Go cannot resolve the replacement revision.

A malformed semantic version in the replace

A version like v1.4 or 1.4.9 (missing patch component or the v prefix) is not a valid module version, so Go rejects the directive.

How to fix it

Pin a version the replacement actually has

List the fork’s tags and replace with one that exists, in full vX.Y.Z form.

Terminal

go list -m -versions github.com/fork/lib
go mod edit -replace github.com/org/lib=github.com/fork/lib@v1.4.1
go mod tidy

Use a pseudo-version for an untagged fork commit

If the fork has no tag, let go get compute a pseudo-version for the exact commit.