go: parsing go.mod: unexpected module path \"github.com/x/y\"" after forking a dependency - how to fix

TL;DR: You forked the dependency, but go.mod still declares the original module path, so Go complains the path it found does not match the path it expected. If this repository is the fork, change the module line to the fork's path. If you only consume the fork, keep the module line and add a replace directive pointing the original path at your fork.

go: parsing go.mod: unexpected module path "github.com/x/y"

1. Open go.mod and read the module line. Expected: it declares the original path (for example github.com/x/y) while the code actually lives at the fork's path.

2. Decide which case you are in: this repo IS the fork, or this repo CONSUMES the fork. Expected: you know which fix below applies before editing.

3. If this repo is the fork, change the module line to the fork's path and update imports to match. Expected: go build ./... resolves everything under the fork's path.

4. If this repo consumes the fork, keep the module line and add a replace directive: replace github.com/x/y => github.com/[your-fork]/y v[version]. Expected: builds fetch the fork's code while imports keep using the original path.

5. Run go mod tidy, then go build ./.... Expected: tidy succeeds and go.sum is updated; the build compiles with no module-path error.

Use this when

• Go fails with the exact "unexpected module path" message naming a quoted path.
• The failure started after forking a dependency on the forge.
• The quoted path in the error differs from the module line in go.mod.

Not for this skill when

• The error is "cannot find package"; the module is missing, not mis-pathed.
• Replace directives form a cycle; that is a replace-graph problem.
• A private module fails with authentication errors; credentials are the issue.

Variant phrasings

• "go.mod unexpected module path after fork"
• "go replace forked dependency"
• "parsing go.mod unexpected module path github"
• "go get fork unexpected module path"

Why it happens

Go requires the module path declared in go.mod to match the path used to fetch and import the module. A fork lives at a different repository path, so the declaration and the reality disagree. Renaming the module line fixes the declaration; a replace directive fixes the resolution while leaving imports untouched.

Edge cases

• A replace pointing at a local directory needs no version; a replace pointing at another remote needs a version or pseudo-version.
• Use a pseudo-version (from go get github.com/[your-fork]/y@[commit]) to pin the fork to an exact commit.
• Do not commit a replace directive in a published library; replaces do not propagate to consumers.
• Vanity import paths add another layer: the module line must match the vanity path, not the repository URL.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstW5EfQ3VYbAcoC4J4Sf8hw