Fix: no required module provides package / cannot find package in Go

The Error

You try to build or run your Go code and get one of these:

Missing module dependency:

main.go:5:2: no required module provides package github.com/gin-gonic/gin; to add it:
	go get github.com/gin-gonic/gin

No go.mod file:

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

Package not in go.mod:

could not import github.com/gorilla/mux (no required module provides package "github.com/gorilla/mux")

Legacy GOPATH error (Go 1.11–1.15 era):

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

All of these mean the same thing: Go can’t locate a package you’re importing. The cause depends on whether you’re using Go modules (the modern system) or the legacy GOPATH mode.

Why This Happens

Since Go 1.16, Go modules are the default dependency system. Every Go project needs a go.mod file that declares the module path and lists its dependencies. When Go can’t find a package, it’s usually because:

• No go.mod file exists. You’re in a directory without a module definition.
• The dependency isn’t listed in go.mod. You added an import but didn’t run go get or go mod tidy to fetch it.
• GO111MODULE is set to off. This forces Go into legacy GOPATH mode, where modules are ignored entirely.
• The module proxy can’t reach the package. The default proxy (proxy.golang.org) doesn’t have the module, or your network blocks it.
• The package is in a private repository. The module proxy and checksum database can’t access private repos without configuration.
• A major version mismatch. Go enforces major version suffixes (/v2, /v3, etc.) in import paths for modules at v2 or higher.
• The vendor directory is stale. You’re using vendoring but haven’t updated the vendor directory after adding a new dependency.
• Workspace mode interference. A go.work file changes how Go resolves modules, which can cause unexpected resolution failures.

Fix 1: Initialize a Go Module

If you don’t have a go.mod file, create one:

go mod init github.com/yourname/yourproject

Replace the module path with your actual repository path. For a project that won’t be imported by others, any name works:

go mod init myapp

Then download your dependencies:

go mod tidy

go mod tidy reads all the import statements in your .go files, adds missing dependencies to go.mod, and removes unused ones. This is the single most useful command for fixing module issues.

Fix 2: Add the Missing Dependency

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

go get github.com/gin-gonic/gin

Or let go mod tidy figure out everything at once:

go mod tidy

go get vs go mod tidy: Use go get when you want to add or update a specific package. Use go mod tidy to sync go.mod with all the imports in your code. In practice, running go mod tidy after adding new imports is the most reliable approach.

To add a specific version:

go get github.com/gin-gonic/gin@v1.9.1

To get the latest version:

go get github.com/gin-gonic/gin@latest

Fix 3: Check GO111MODULE

GO111MODULE controls whether Go uses modules or GOPATH mode. Check its value:

go env GO111MODULE

• on (default since Go 1.16) — Go modules are always used. This is what you want.
• off — Go modules are disabled. Go looks for packages in GOPATH/src instead. This causes cannot find package errors for anything not manually placed in GOPATH.
• auto — Go uses modules if a go.mod file exists in the current directory or any parent.

If it’s set to off, fix it:

go env -w GO111MODULE=on

Or set it for the current session:

export GO111MODULE=on

On Windows (PowerShell):

$env:GO111MODULE = "on"

Note: If you’re on Go 1.21+, GO111MODULE defaults to on and you rarely need to touch it. This issue mostly appears when working with old tutorials, legacy projects, or CI configurations that explicitly set GO111MODULE=off.

Fix 4: Fix the Import Path

Go import paths are case-sensitive and must exactly match the module path declared in that module’s go.mod.

Common mistakes

// Wrong -- capital letter
import "github.com/Gorilla/mux"

// Correct
import "github.com/gorilla/mux"

// Wrong -- missing the actual package path
import "github.com/aws/aws-sdk-go-v2"

// Correct -- you import specific sub-packages
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"

Internal packages

If you’re importing a package from within your own module, the import path must start with your module path:

// go.mod declares: module github.com/yourname/myapp

// Wrong
import "myapp/internal/database"

// Correct
import "github.com/yourname/myapp/internal/database"

Check your module name in go.mod and make sure your import paths use that exact prefix.

Fix 5: Fix Major Version Suffixes

Go’s module system requires that modules at v2 or higher include the major version in the import path. This is a common source of confusion.

If a library has released v2:

// Wrong -- this imports v1 (or v0)
import "github.com/example/lib"

// Correct -- v2 requires the /v2 suffix
import "github.com/example/lib/v2"

And in go.mod:

require github.com/example/lib/v2 v2.3.0

If you see go get fetching v0.0.0 when you expected v2+, you’re missing the version suffix in the import path.

To find out what major versions a module has published:

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

Fix 6: Configure Private Repositories

The default Go module proxy (proxy.golang.org) and checksum database (sum.golang.org) can’t access private repositories. You’ll see errors like:

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

Or:

verifying github.com/yourcompany/private-lib@v1.0.0: checksum mismatch

Set GOPRIVATE

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

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

This sets both GONOSUMDB and GONOPROXY for matching patterns. Multiple patterns are comma-separated:

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

Configure Git authentication

Go fetches modules using git under the hood. For private repos, you need authentication configured:

HTTPS with a token (GitHub):

git config --global url."https://YOUR_TOKEN@github.com/".insteadOf "https://github.com/"

SSH:

git config --global url."git@github.com:".insteadOf "https://github.com/"

Make sure your SSH keys are set up and added to your Git host. If you’re in CI/CD, use a deploy key or machine user token.

GONOSUMDB and GONOPROXY

If you need finer control than GOPRIVATE:

# Skip the checksum database for these modules
go env -w GONOSUMDB=github.com/yourcompany/*

# Skip the proxy for these modules (fetch directly from the source)
go env -w GONOPROXY=github.com/yourcompany/*

GOPRIVATE sets both at once. Use the individual variables when you want different patterns for each.

Fix 7: Fix Proxy Settings (GOPROXY)

Check your current proxy configuration:

go env GOPROXY

The default is https://proxy.golang.org,direct. This means Go first tries the proxy, then falls back to fetching directly from the source.

If the proxy is unreachable (corporate firewall, air-gapped network, or regional restrictions):

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

# Or use a mirror (common in China)
go env -w GOPROXY=https://goproxy.cn,direct

If GOPROXY is set to off, no modules can be downloaded at all:

# This breaks everything
go env -w GOPROXY=off

# Fix it
go env -w GOPROXY=https://proxy.golang.org,direct

GONOSUMCHECK

If you’re getting checksum verification errors:

verifying github.com/example/lib@v1.0.0: checksum mismatch

This means the module’s content doesn’t match what’s recorded in go.sum or the checksum database. Don’t blindly disable verification — this protects against tampered dependencies.

First, try deleting go.sum and regenerating it:

rm go.sum
go mod tidy

If the checksum database itself is the issue (private modules, forks), use GONOSUMDB:

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

Fix 8: Use the replace Directive

The replace directive in go.mod lets you redirect a module to a different location. This is useful for local development, forks, and fixing broken dependencies.

Local development

Point a dependency to a local directory:

// go.mod
module myapp

go 1.21

require github.com/example/lib v1.2.0

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

The local path must contain a go.mod file. This is how you develop a library and a consumer simultaneously without publishing every change.

Using a fork

Point to your fork of a module:

replace github.com/original/lib => github.com/yourfork/lib v1.2.1-fixed

Fixing a vanished module

If a module was deleted from its original location:

replace github.com/deleted/lib v1.0.0 => github.com/archived/lib v1.0.0

Warning: Don’t commit replace directives that point to local paths. They’ll break for everyone else. Use them only during development. For libraries (modules imported by others), Go ignores replace directives in dependencies’ go.mod files — they only apply in the main module.

Fix 9: Fix the Vendor Directory

If your project uses vendoring (go mod vendor), the vendor/ directory must be kept in sync with go.mod.

Symptoms

cannot find package "github.com/example/lib" in any of:
	/home/user/myapp/vendor/github.com/example/lib

Fix

Regenerate the vendor directory:

go mod vendor

Then build with the vendor flag:

go build -mod=vendor ./...

If you want Go to always use the vendor directory:

go env -w GOFLAGS=-mod=vendor

When does vendoring matter?

Go automatically detects the vendor/ directory only in the main module and only if go.mod declares Go 1.14 or later. If you’re in a subdirectory or the Go version in go.mod is too old, Go might ignore the vendor directory. Make sure your go.mod has a recent Go version:

go 1.21

Fix 10: Fix Workspace Mode (go.work)

Go 1.18 introduced workspaces (go.work) for working with multiple modules simultaneously. If a go.work file exists in your directory tree, it changes how Go resolves modules.

Symptoms

You get no required module provides package even though the package is in your go.mod. This happens when go.work doesn’t include your module.

Check for a go.work file

go env GOWORK

If this prints a path, workspace mode is active.

Fix

Either add your module to the workspace:

go work use ./my-module

Or disable workspace mode for a single command:

GOWORK=off go build ./...

To permanently remove workspace mode, delete the go.work file:

rm go.work go.work.sum

Note: go.work should typically be listed in .gitignore. It’s a local development tool, not something that should be committed — unless your team has agreed on a shared workspace configuration.

Edge Cases

Importing a package vs. a module

In Go, a module is a collection of packages defined by a go.mod file. A package is a single directory of .go files. You import packages, not modules.

// This imports the package "mux" from the module "github.com/gorilla/mux"
import "github.com/gorilla/mux"

// This imports the package "s3" from the module "github.com/aws/aws-sdk-go-v2"
import "github.com/aws/aws-sdk-go-v2/service/s3"

If a module has no Go files in its root directory, you can’t import the module path itself — you need to import a sub-package.

Build tags excluding files

If all .go files in a package have build tags that don’t match your platform, Go treats the package as empty:

package example/foo: build constraints exclude all Go files in /path/to/foo

Check the build tags at the top of the .go files:

//go:build linux
// +build linux

If you’re on macOS or Windows and all files are tagged linux, Go sees no valid source files. You need files without restrictive build tags, or files tagged for your platform.

CGO and missing C dependencies

If a package uses CGO and you get cannot find package alongside C compiler errors, the issue is likely missing C libraries or a disabled CGO:

# Check if CGO is enabled
go env CGO_ENABLED

If it’s 0 and the package requires CGO, enable it:

go env -w CGO_ENABLED=1

You’ll also need a C compiler (gcc or clang) and the required C libraries installed on your system.

Packages in GOROOT

If the error mentions GOROOT:

cannot find package "fmt" in any of:
	/usr/local/go/src/fmt (from $GOROOT)

Your Go installation is broken or GOROOT points to the wrong location. Check it:

go env GOROOT
ls "$(go env GOROOT)/src/fmt"

If the directory doesn’t exist, reinstall Go or fix GOROOT:

# Check where Go is actually installed
which go

Note: You almost never need to set GOROOT manually. The Go binary knows where it was installed. Setting GOROOT incorrectly is a common cause of this error.

Still Not Working?

Clear the module cache

Go caches downloaded modules in GOPATH/pkg/mod. A corrupted cache can cause strange resolution failures:

go clean -modcache
go mod tidy

Warning: This deletes all cached modules. Your next build will re-download everything.

Check your Go version

Some modules require a minimum Go version. Check your version:

go version

If the module’s go.mod declares go 1.21 and you’re running Go 1.19, you’ll get errors. Update Go or use a compatible version of the dependency.

Verify go.sum integrity

If go.sum has stale or incorrect entries, delete it and regenerate:

rm go.sum
go mod tidy

This forces Go to re-verify all module checksums.

Check for typos in go.mod

Open go.mod and verify the module path is correct. A common mistake is a trailing slash or wrong casing:

// Wrong
module github.com/YourName/MyApp/

// Correct
module github.com/yourname/myapp

IDE not recognizing packages

If your code compiles from the command line but your IDE shows red squiggles, the IDE’s Go tooling is out of sync.

VS Code (gopls): Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run “Go: Restart Language Server”. If that doesn’t work, try “Go: Reset Go tools”. Also make sure gopls is up to date:

go install golang.org/x/tools/gopls@latest

GoLand: Go to File → Invalidate Caches → Invalidate and Restart.

Dependency behind a corporate proxy or VPN

If go get hangs or times out, your network might be blocking access to the Go proxy or the source repository. This is similar to curl connection failures caused by network restrictions. Try fetching directly:

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

If that also fails, check your corporate proxy settings:

# Set HTTP proxy
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

go get github.com/example/lib

Related: If you’re hitting a similar error in Node.js, see Fix: Error Cannot find module (Node.js). For Python, see Fix: ModuleNotFoundError: No module named. For bundler errors in frontend projects, see Fix: Module not found: Can’t resolve.