Go Module Path Mismatch Error "Module Declares Its Path as X but Loaded as Y"

This error means the module path declared in a project's go.mod file doesn't match the import path Go is actually trying to use to reach it — Go requires these to agree exactly, since the module path is what every import statement throughout the ecosystem uses to reference that specific module.

The Problem

Building or running a Go project fails with:

go: github.com/username/reponame@v1.2.0: parsing go.mod:
    module declares its path as: github.com/username/oldreponame
        but was required as: github.com/username/reponame

The project might have built and run fine before, with the failure appearing after a specific change — a repository rename, a fork, or a manual edit to go.mod.

Why It Happens

The module directive at the top of go.mod declares what a module considers its own canonical import path to be — and Go's tooling cross-checks this declared path against the actual path being used to fetch/import it, refusing to proceed if they don't match, since a mismatch could indicate you're accidentally pulling in the wrong code, or that the module's own configuration is out of sync with reality. Common causes:

• A GitHub repository was renamed after the module was first published, but the module directive inside go.mod was never updated to reflect the new repository name/path
• A project was forked, and the fork's go.mod still declares the original repository's module path rather than being updated to the fork's own new path
• A local module was manually copied or renamed on disk, but its internal go.mod declaration still references the old name/location
• A typo was introduced when manually editing go.mod, creating a mismatch between the declared path and what other files or configuration actually expect

The Fix

If you're the maintainer of the module and it was genuinely renamed (a repository rename, moving to a new organization), update the module directive in go.mod to match the new, correct path:

module github.com/username/reponame

go 1.21

After updating go.mod, also update every internal import statement within the module's own code that references its own old path, since these need to match the newly declared module path exactly:

// Before
import "github.com/username/oldreponame/internal/utils"

// After
import "github.com/username/reponame/internal/utils"

A find-and-replace across the codebase for the old module path, substituting the new one, handles this efficiently for larger projects:

grep -rl "github.com/username/oldreponame" . | xargs sed -i 's|github.com/username/oldreponame|github.com/username/reponame|g'

If you're consuming someone else's module as a dependency and hit this error, it typically means the module's own go.mod is genuinely inconsistent with its published location — this is the module author's issue to fix, not something you can correctly resolve purely from the consuming side. In the meantime, you can work around it using a replace directive in your own go.mod, pointing explicitly at the correct source:

// your project's go.mod
require github.com/username/reponame v1.2.0

replace github.com/username/reponame => github.com/username/reponame v1.2.0

Or, if you need to reference a fork with a mismatched internal module declaration, replace with an explicit reference to the fork's actual location:

replace github.com/original/module => github.com/yourfork/module v1.0.0

Report the issue to the module's maintainer if it's a third-party dependency with this inconsistency, since it will likely affect other consumers as well, and the actual fix belongs in that module's own repository and go.mod, not something every individual consumer should need to work around independently with their own replace directives.

Still Not Working?

If you've corrected the module path and internal imports but still see inconsistent behavior, clear Go's module cache, since it may have cached the module under its old, now-incorrect path information from before your fix:

go clean -modcache
go mod tidy

This forces Go to re-fetch and re-verify every dependency from scratch, ensuring nothing stale from before the path correction lingers in the local cache and continues causing the same mismatch error even after the underlying go.mod issue has genuinely been fixed.