Fix: Go Module Not Found – cannot find module providing package

The Error

You try to build or run your Go project and the compiler stops with one of these messages:

Missing module:

go: cannot find module providing package github.com/labstack/echo/v4

No go.mod present:

go: cannot find main module, but found .git/config in /home/user/project
	to create a module there, run:
	go mod init

Module not in requirements:

main.go:5:2: no required module provides package github.com/spf13/cobra; to add it:
	go get github.com/spf13/cobra

Checksum verification failure:

verifying github.com/example/[email protected]: checksum mismatch
	downloaded: h1:abc123...
	go.sum:     h1:def456...

Legacy GOPATH resolution failure:

cannot find package "github.com/sirupsen/logrus" in any of:
	/usr/local/go/src/github.com/sirupsen/logrus (from $GOROOT)
	/home/user/go/src/github.com/sirupsen/logrus (from $GOPATH)

Every variation points to the same root problem: Go cannot locate a package your code imports. The underlying cause ranges from a missing go.mod file to proxy misconfigurations, private repository access issues, or stale dependency caches. The fixes below walk through each scenario systematically.

Why This Happens

Go’s module system, the default since Go 1.16, requires a go.mod file at the root of every project. This file declares the module’s identity (its module path), the minimum Go version, and every external dependency the project needs. When you write an import statement in a .go file, the compiler resolves that import by looking up the package in the dependency graph defined by go.mod and verified by go.sum.

When the compiler says it cannot find a module providing a package, it means one of the links in that chain is broken. Either there is no go.mod at all, or the dependency is not listed in go.mod, or the dependency is listed but the Go toolchain cannot download it (due to network, proxy, authentication, or checksum issues).

Before Go modules existed, Go used the GOPATH workspace model. All source code lived under $GOPATH/src, and package resolution was a simple directory lookup. The GOPATH model had no versioning, no checksums, and no dependency isolation between projects. If you are still seeing GOPATH-style error messages (mentioning $GOROOT and $GOPATH), your environment is either stuck in legacy mode or your GO111MODULE setting is wrong.

Understanding the difference between these two systems is critical. Modules give you reproducible builds, version pinning, and checksum verification. GOPATH gives you none of that. Every modern Go project should use modules. If you are starting a new project or migrating an old one, the first step is always go mod init.

Fix 1: Initialize a Module with go mod init

If there is no go.mod file in your project, Go cannot resolve any imports beyond the standard library. Create one:

go mod init github.com/yourname/yourproject

The argument is the module path. For a project hosted on GitHub, use the repository URL without the https:// prefix. For a project that will not be published or imported by other modules, any name works:

go mod init myapp

After creating the module, pull in all dependencies your code references:

go mod tidy

This command scans every .go file in the module, adds missing require directives to go.mod, removes any require entries that are no longer referenced, and updates go.sum with the correct checksums. Run go mod tidy whenever you add or remove imports. It is the single most reliable way to keep go.mod in sync with your actual code.

If your project was previously using GOPATH mode, go mod init followed by go mod tidy handles the entire migration. Go reads existing dependency metadata from Gopkg.lock (dep), glide.lock, vendor.json, and other legacy formats if they exist.

Fix 2: Add Missing Dependencies with go get and go mod tidy

If go.mod already exists but a specific package is missing, add it explicitly:

go get github.com/labstack/echo/v4

To pin a specific version:

go get github.com/labstack/echo/[email protected]

To get the latest available version:

go get github.com/labstack/echo/v4@latest

Alternatively, let go mod tidy discover and add all missing dependencies at once:

go mod tidy

The difference between go get and go mod tidy matters. go get targets a specific module — you control the version precisely and can upgrade or downgrade individual dependencies. go mod tidy is broader — it reconciles go.mod with every import in your source tree. In daily development, the pattern is: write your code with the imports you need, run go mod tidy, and let Go handle the rest.

If you get an error like go get: module github.com/example/lib: no matching versions for query "latest", the module either does not exist at that path or the proxy cannot find it. Double-check the import path for typos. Import paths are case-sensitive and must match the module’s declared path exactly. This kind of path mismatch is conceptually similar to environment variable errors where a small typo causes the runtime to look in the wrong place entirely.

Fix 3: Resolve GOPATH vs Modules Conflicts

If you see errors referencing $GOPATH and $GOROOT, your Go installation may be running in legacy GOPATH mode. Check the GO111MODULE setting:

go env GO111MODULE

The value should be on (the default since Go 1.16). If it is off or auto, set it explicitly:

go env -w GO111MODULE=on

For the current shell session only:

export GO111MODULE=on

On Windows (PowerShell):

$env:GO111MODULE = "on"

When GO111MODULE=off, Go ignores go.mod entirely and falls back to looking for packages under $GOPATH/src. This is almost never what you want in modern Go development. The auto setting uses modules only when a go.mod file exists in the current directory or a parent directory, which can lead to confusing behavior when you run commands from subdirectories.

If you are working on a legacy project that genuinely relies on GOPATH, you have two choices: migrate to modules (recommended) or keep GO111MODULE=off and manage dependencies manually. Migration is straightforward — go mod init handles most of the work, and the community has moved decisively toward modules.

Also verify that GOPATH itself is set correctly:

go env GOPATH

The default is $HOME/go. If it points somewhere unexpected, binaries installed with go install and cached modules might end up in the wrong location. You can reset it:

go env -w GOPATH=$HOME/go

Fix 4: Configure GOPRIVATE for Private Repositories

The Go module proxy at proxy.golang.org and the checksum database at sum.golang.org are public services. They cannot access private repositories. When Go tries to fetch a private module through the proxy, you get errors like:

go: module github.com/yourcompany/internal-lib: reading https://proxy.golang.org/...: 410 Gone

Or a 403 Forbidden, or a timeout.

Tell Go to bypass the proxy and checksum database for your private modules:

go env -w GOPRIVATE=github.com/yourcompany/*

This sets both GONOPROXY and GONOSUMDB for the matching pattern. You can specify multiple patterns separated by commas:

go env -w GOPRIVATE=github.com/yourcompany/*,gitlab.internal.com/*

After setting GOPRIVATE, Go fetches those modules directly from the source using Git. This means you need Git authentication configured for those hosts. For HTTPS access with a personal access token:

git config --global url."https://[email protected]/".insteadOf "https://github.com/"

For SSH access:

git config --global url."[email protected]:".insteadOf "https://github.com/"

Make sure your SSH keys are properly configured and added to the remote host. If you are running into SSH authentication issues, see Fix: Git SSH Permission Denied for a detailed walkthrough of key generation, ssh-agent configuration, and host verification.

In CI/CD pipelines, use a deploy key or machine user token rather than your personal credentials. Store the token as a secret in your CI system and inject it into the Git configuration at build time.

Fix 5: Fix go.sum Verification Errors

The go.sum file records the expected cryptographic hash of every module version your project depends on. When Go downloads a module and the hash does not match what is in go.sum, you get a checksum mismatch error. This is a security feature — it prevents tampered or corrupted dependencies from entering your build.

Common causes of checksum mismatches:

• Someone edited go.sum manually or merged conflicting changes.
• The module author republished the same version with different content (a serious practice violation, but it happens).
• The go.sum file was generated on a different platform or Go version that produced different artifacts.

The safest fix is to delete go.sum and regenerate it:

rm go.sum
go mod tidy

This downloads all dependencies fresh and writes correct checksums. If the module’s content genuinely changed at the source, you will get a new valid checksum. Compare the regenerated go.sum with what was committed to verify nothing unexpected changed.

If the mismatch involves a private module that should not be verified against the public checksum database, configure GONOSUMDB:

go env -w GONOSUMDB=github.com/yourcompany/*

Or use GOPRIVATE, which sets GONOSUMDB as well. Do not disable checksum verification globally — it exists to protect your supply chain.

Fix 6: Use the replace Directive for Local Development

The replace directive in go.mod redirects a module to a different location. This is indispensable during local development when you need to test changes to a dependency without publishing it.

Point a dependency to a local directory:

// go.mod
module myapp

go 1.22

require github.com/example/lib v1.5.0

replace github.com/example/lib => ../lib

The local path must contain its own go.mod file. This lets you edit the library and consumer side by side, testing changes immediately without tagging a release.

Point to a fork:

replace github.com/original/lib => github.com/yourfork/lib v1.5.1-patched

Fix a module that has been deleted or moved:

replace github.com/deleted/lib v1.0.0 => github.com/community-fork/lib v1.0.1

Real-world scenario: A developer clones a project, runs go build, and gets “cannot find module.” They have Go installed but never ran go mod tidy after cloning. The go.mod lists dependencies, but none are downloaded yet. Running go mod tidy (or even just go build, which fetches dependencies automatically since Go 1.17) resolves it instantly.

Important caveats: never commit replace directives that point to local paths. They will break the build for every other developer and in CI. If your module is a library imported by others, Go ignores replace directives in dependency go.mod files — they only take effect in the main module. For collaborative local development across multiple modules, consider go.work workspaces instead, which provide a cleaner mechanism for multi-module development.

Fix 7: Update the Vendor Directory

If your project uses vendoring, all dependencies are copied into a vendor/ directory within your project tree. This provides hermetic builds that do not require network access, which is useful in air-gapped environments or CI systems with restricted connectivity.

When you add a new dependency but forget to update the vendor directory, Go cannot find the package in vendor/ and reports a module-not-found error.

Regenerate the vendor directory:

go mod vendor

Build using the vendor directory:

go build -mod=vendor ./...

To make Go always use vendored dependencies without the flag:

go env -w GOFLAGS=-mod=vendor

Go automatically detects and uses vendor/ in the main module if go.mod declares Go 1.14 or later. If your go.mod has an older version in its go directive, Go might silently ignore the vendor directory. Update the directive:

go 1.22

Keep vendor/ in sync by running go mod vendor after every go get or go mod tidy. Some teams add a CI check that runs go mod vendor and then verifies git diff --exit-code vendor/ to catch cases where someone updated go.mod but forgot to re-vendor. This is similar to how Docker build failures often stem from stale or missing files that the build process expects to find in a specific location.

Fix 8: Configure Proxy Settings (GOPROXY)

The GOPROXY environment variable controls where Go downloads modules from. Check the current value:

go env GOPROXY

The default is https://proxy.golang.org,direct. Go first queries the proxy; if the module is not found there, it falls back to fetching directly from the version control system.

If the proxy is unreachable due to a corporate firewall or regional restriction:

# Bypass the proxy entirely
go env -w GOPROXY=direct

If you are in a region where proxy.golang.org is slow or blocked, use a regional mirror:

go env -w GOPROXY=https://goproxy.cn,direct

If GOPROXY is set to off, all module downloads are disabled:

# This prevents any module from being fetched
GOPROXY=off

# Reset to default
go env -w GOPROXY=https://proxy.golang.org,direct

You can chain multiple proxies. Go tries them in order, falling through on 404 or 410 responses:

go env -w GOPROXY=https://proxy.company.com,https://proxy.golang.org,direct

If you are behind a corporate HTTP proxy (not the Go module proxy — the network-level proxy), configure the standard environment variables:

export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

Network connectivity issues overlap with many other development tools. If go get hangs or times out, the same network path that blocks Go modules may also affect npm dependency resolution or Git operations.

Fix 9: Handle Go Version Compatibility

The go directive in go.mod specifies the minimum Go version required to build the module:

module myapp

go 1.22

If a dependency’s go.mod declares go 1.22 but you are running Go 1.20, the toolchain may refuse to fetch or build that dependency. Starting with Go 1.21, the go directive is enforced more strictly — the toolchain will not compile modules that require a newer version of Go than what you have installed.

Check your installed Go version:

go version

Check what version a dependency requires:

go list -m -json github.com/example/lib@latest

The GoVersion field in the JSON output tells you what that module needs.

If you cannot upgrade your Go installation, pin the dependency to an older version that supports your Go release:

go get github.com/example/[email protected]

Go 1.21 also introduced the toolchain directive in go.mod, which lets you specify which Go toolchain version to use for building the module. If you see errors related to toolchain compatibility:

go: module requires Go >= 1.22.0 (running go 1.21.5; GOTOOLCHAIN=local)

You can either upgrade Go, or allow automatic toolchain downloads:

go env -w GOTOOLCHAIN=auto

With GOTOOLCHAIN=auto, Go downloads and uses the required toolchain version automatically. This is convenient but means your build depends on network access to fetch toolchains. For reproducible CI builds, install the exact Go version you need explicitly.

The go directive also affects which language features are available. If you use a Go 1.22 feature like range-over-integer but your go.mod says go 1.21, the compiler rejects it. Keep the go directive aligned with the features you actually use:

go mod tidy -go=1.22

This updates the go directive and adjusts go.sum entries accordingly.

Still Not Working?

Why this matters: Go’s module system is designed for reproducible builds. The go.sum file acts as a lockfile, pinning exact content hashes for every dependency. If you skip go mod tidy or delete go.sum without regenerating it, you lose this reproducibility guarantee and risk pulling in tampered or incompatible versions.

Clear the module cache

Go caches downloaded modules in $GOPATH/pkg/mod. A corrupted or stale cache can cause phantom resolution failures:

go clean -modcache
go mod tidy

This deletes all cached modules. Your next build will re-download everything, which takes time but eliminates cache-related issues.

Inspect the full module graph

If you cannot figure out which dependency is causing the problem, dump the full module dependency graph:

go mod graph

This prints every module and its dependencies. Search for the problematic package path to see where it enters the dependency tree.

For a more readable view:

go mod why github.com/example/lib

This shows the shortest chain of imports from your code to the specified module. If it says (main module does not need module github.com/example/lib), the import might be in a file excluded by build tags, or the import was removed but go.mod was not updated.

Verify the module exists

Check that the module is actually published and accessible:

go list -m -versions github.com/example/lib

If this returns nothing, the module either does not exist at that path, has not been published to the proxy yet, or the proxy has not indexed it. Newly published modules can take a few minutes to appear on proxy.golang.org. You can force a fetch:

GOPROXY=direct go get github.com/example/lib@latest

Check for workspace interference

If you have a go.work file in your directory tree, it overrides normal module resolution:

go env GOWORK

If this prints a path, workspace mode is active. Either add your module to the workspace or disable it:

GOWORK=off go build ./...

Rebuild after Go upgrades

After upgrading Go itself, run a clean rebuild:

go clean -cache
go mod tidy
go build ./...

The build cache from a previous Go version can sometimes cause stale references. Cleaning it forces a full recompilation.

Variables declared and not used

If after fixing module resolution you hit declared and not used compiler errors, that is a separate Go strictness rule. See Fix: Go declared and not used for a complete guide to resolving unused variable and import errors.

Related: For module resolution errors in Node.js, see Fix: npm ERESOLVE unable to resolve dependency tree. For environment configuration issues, see Fix: env variable undefined. For Docker build path problems, see Fix: Docker build failed. For Git SSH authentication, see Fix: Git SSH Permission Denied.