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

The Error

You run go build, go run, or go test and hit one of these messages:

Module dependency missing:

main.go:4:2: no required module provides package github.com/redis/go-redis/v9; to add it:
	go get github.com/redis/go-redis/v9

Package not found anywhere:

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)

Module resolution failure:

go: cannot find module providing package github.com/jackc/pgx/v5

Missing main module:

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

These errors all point to the same root problem: Go cannot locate a package your code imports. The fix depends on what’s actually wrong — a missing dependency, a bad import path, a module configuration issue, or an environment problem.

Why This Happens

Go’s module system (the default since Go 1.16) resolves packages through a chain of lookups. When any link in that chain breaks, you get a “cannot find package” error. Here is what Go checks, in order:

1. The standard library. Go looks for the package in $GOROOT/src/. If you import fmt or net/http, it comes from here.
2. The go.mod file. Go reads your module’s go.mod to find which version of a dependency to use. If the package isn’t listed (directly or transitively), resolution fails.
3. The module cache. Downloaded modules live in $GOPATH/pkg/mod/. If the module isn’t cached, Go fetches it from the module proxy.
4. The module proxy. By default, Go hits proxy.golang.org to download modules. If the proxy can’t find the module (or can’t access it), the fetch fails.
5. Direct source. If the proxy falls through to direct, Go tries to git clone (or hg clone, etc.) the repository directly.

The error fires when every step in this chain fails for your package. Common causes include:

• No go.mod file. The project hasn’t been initialized as a Go module.
• Dependency not in go.mod. You added an import statement but never ran go get or go mod tidy.
• Wrong import path. A typo, wrong casing, or missing major version suffix (/v2) in the import.
• Module path mismatch in go.mod. Your go.mod declares a different module path than what your imports reference.
• GOPATH vs modules confusion. GO111MODULE is set to off, forcing legacy GOPATH mode.
• Private repository. The module proxy and checksum database cannot reach private repos.
• Stale vendor directory. The vendor/ folder doesn’t include the new dependency.
• Workspace mode interference. A go.work file is changing module resolution.

Fix 1: Run go mod tidy to Sync Dependencies

This is the fix that works 80% of the time. Run it first:

go mod tidy

go mod tidy scans every .go file in your module, finds all import statements, adds missing dependencies to go.mod, removes unused ones, and updates go.sum. It’s the single command that keeps your dependency graph consistent.

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

go mod init github.com/yourname/yourproject
go mod tidy

For projects that won’t be imported by others, any module path works:

go mod init myapp
go mod tidy

After running go mod tidy, try building again. If the error is gone, you’re done. If not, the cause is deeper — keep reading.

Note: go mod tidy requires network access to resolve new dependencies. If you’re behind a firewall or offline, see Fix 6 (private repos) or the proxy section under “Still Not Working?”

Fix 2: Run go mod download to Fetch Modules

Sometimes your go.mod and go.sum are correct, but the modules aren’t in your local cache. This happens after cloning a repo, switching machines, or clearing the module cache:

go mod download

This downloads every module listed in go.mod without modifying any files. It’s a pure fetch operation.

To download a specific module:

go mod download github.com/redis/go-redis/v9

To verify downloads match their expected checksums:

go mod download -x

The -x flag prints the commands Go executes, which is useful for debugging network or authentication issues.

If go mod download fails with a 410 or 404 error, the module might not exist on the proxy. Check the import path is correct and try fetching directly:

GOPROXY=direct go mod download

Pro Tip: Run go mod download in your CI/CD pipeline as a separate caching step before go build. This lets you cache the module download independently from the build, speeding up subsequent pipeline runs significantly. Most CI systems (GitHub Actions, GitLab CI) can cache $GOPATH/pkg/mod between jobs.

Fix 3: Fix Your go.mod Module Path

The module path in go.mod must match what your import statements use. If they diverge, Go can’t resolve internal packages.

Check your go.mod:

module github.com/yourname/myapp

go 1.22

Every import of an internal package must use that exact module path as its prefix:

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

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

// Wrong -- using a short name instead of the module path
import "myapp/internal/database"

// Wrong -- different casing
import "github.com/YourName/MyApp/internal/database"

Common mistakes with go.mod module paths:

Trailing slash:

// Wrong
module github.com/yourname/myapp/

// Correct
module github.com/yourname/myapp

Mismatch after renaming a repo:

If you renamed your GitHub repository from old-name to new-name, update go.mod:

// Old
module github.com/yourname/old-name

// New
module github.com/yourname/new-name

Then update every import statement across your codebase. Use your editor’s find-and-replace or a tool like gofmt with sed:

find . -name '*.go' -exec sed -i 's|github.com/yourname/old-name|github.com/yourname/new-name|g' {} +

After changing the module path, run go mod tidy to clean up.

Fix 4: Fix Import Path Typos and Case Sensitivity

Go import paths are case-sensitive and must exactly match the module’s declared path. Even one wrong character causes a “cannot find package” error.

Wrong casing:

// Wrong
import "github.com/Sirupsen/logrus"

// Correct (the author changed the GitHub username to lowercase)
import "github.com/sirupsen/logrus"

Missing sub-package path:

// Wrong -- this is the module root, not an importable package
import "github.com/aws/aws-sdk-go-v2"

// Correct -- import the actual package you need
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/dynamodb"

Missing major version suffix:

Go requires modules at v2 or higher to include the major version in the import path. This is a frequent source of confusion and is related to how Go modules resolve versions.

// Wrong -- this gets v0 or v1
import "github.com/jackc/pgx"

// Correct -- v5 requires the /v5 suffix
import "github.com/jackc/pgx/v5"

The require line in go.mod must also use the suffix:

require github.com/jackc/pgx/v5 v5.5.0

Vanity import paths:

Some projects use custom import paths that differ from their repository URL. For example, go.uber.org/zap is hosted at github.com/uber-go/zap, but you must import it using the vanity URL:

// Correct
import "go.uber.org/zap"

// Wrong -- this is the GitHub repo URL, not the import path
import "github.com/uber-go/zap"

Check the project’s documentation or go.mod file for the correct import path.

Common Mistake: Copying import paths from old blog posts or Stack Overflow answers. Module paths change over time — authors rename repos, migrate to vanity URLs, or release major versions. Always check the module’s current documentation or pkg.go.dev page for the correct import path.

Fix 5: Fix GOPATH vs Go Modules Confusion

If your error mentions $GOPATH instead of module-related messages, you might be stuck in legacy GOPATH mode. Check your GO111MODULE setting:

go env GO111MODULE

• on (default since Go 1.16): Go modules are always active. This is correct.
• off: Modules are disabled. Go looks for packages in $GOPATH/src/ using the old vendoring model.
• auto: Go uses modules only if a go.mod file exists in the current or parent directory.

If it’s off, fix it:

go env -w GO111MODULE=on

Or set it for the current shell session:

export GO111MODULE=on

On Windows (PowerShell):

$env:GO111MODULE = "on"

This issue typically appears when working with old CI configurations, legacy Dockerfiles, or tutorials written before Go 1.16. If you find GO111MODULE=off in a Dockerfile or CI script, remove it. Modern Go (1.21+) defaults to on and rarely needs this variable set at all.

If you’re working on a genuinely legacy project that hasn’t been migrated to modules, initialize it:

cd /path/to/project
go mod init github.com/yourname/project
go mod tidy

This creates go.mod and go.sum, converting the project from GOPATH mode to modules. Review the generated go.mod to ensure dependencies look correct, similar to how you’d verify unused variables after a refactor.

Fix 6: Fix Private Repository Access

When you import a package from a private GitHub, GitLab, or Bitbucket repository, the default module proxy (proxy.golang.org) can’t access it. You’ll see:

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

Or a checksum mismatch:

verifying github.com/yourcompany/[email protected]: checksum mismatch

Set GOPRIVATE

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

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

Multiple patterns are comma-separated:

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

GOPRIVATE is shorthand that sets both GONOPROXY (skip the proxy) and GONOSUMDB (skip the checksum database) for matching modules.

Configure Git authentication

Go uses git to fetch modules directly when the proxy is bypassed. Your Git client needs credentials for private repos.

HTTPS with a personal access token (GitHub):

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

SSH instead of HTTPS:

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

Make sure your SSH key is added to your GitHub account. If you’re troubleshooting SSH authentication, see Fix: Git Permission Denied (publickey).

GONOSUMCHECK for checksum bypass

If you need to skip checksum verification for specific modules without skipping the proxy:

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

Warning: Only skip checksum verification for modules you trust. The checksum database protects against supply-chain attacks and tampered dependencies.

CI/CD considerations

In CI pipelines, use environment variables instead of go env -w:

# GitHub Actions example
env:
  GOPRIVATE: github.com/yourcompany/*
  GONOSUMDB: github.com/yourcompany/*

Set up authentication using a machine user token or deploy key, not personal credentials.

Fix 7: Fix Vendor Directory Issues

If your project uses go mod vendor for vendored dependencies, the vendor/ directory must stay in sync with go.mod. When they diverge, you get:

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

Regenerate the vendor directory

go mod vendor

This deletes and recreates vendor/ based on the current go.mod. Then build with vendoring enabled:

go build -mod=vendor ./...

Force vendor mode globally

If your project always uses vendoring:

go env -w GOFLAGS=-mod=vendor

Now every go build, go test, and go run command uses the vendor directory automatically.

When vendor mode kicks in

Go auto-detects the vendor/ directory only in the main module and only if go.mod declares Go 1.14 or later. If your go.mod has an older version, Go ignores vendor/:

// Update this if it's old
go 1.22

Common vendor pitfalls

• Adding a dependency but forgetting go mod vendor. You run go get github.com/new/lib, but the vendor directory still lacks the new package.
• Committing partial vendor updates. If go mod vendor was interrupted or you only committed some files, the vendor directory is inconsistent. Regenerate it fully and commit everything.
• Mixing vendor and non-vendor builds. If some team members use -mod=vendor and others don’t, builds can diverge. Agree on one approach and enforce it in CI.

Fix 8: Fix Go Workspace Mode (go.work)

Go 1.18 introduced workspaces for developing multiple modules simultaneously. A go.work file in your directory tree changes how Go resolves modules, which can cause unexpected “cannot find package” errors.

Detect workspace mode

go env GOWORK

If this prints a file path, workspace mode is active. Go resolves modules through go.work instead of individual go.mod files.

The problem

You have a go.work file that lists some modules but not all. If your module isn’t included in go.work, Go can’t find its packages:

// go.work
go 1.22

use (
    ./service-a
    ./service-b
)
// ./service-c is missing -- its packages won't resolve

Add the missing module

go work use ./service-c

Or edit go.work directly:

go 1.22

use (
    ./service-a
    ./service-b
    ./service-c
)

Disable workspace mode

If you don’t need workspaces and go.work is causing problems, disable it for a single command:

GOWORK=off go build ./...

Or remove the workspace files entirely:

rm go.work go.work.sum

When to use workspaces

Workspaces are useful when you’re developing a library and a service that depends on it simultaneously. Instead of using replace directives in go.mod (which you’d need to remove before committing), go.work handles the local override cleanly.

A typical go.work setup looks like this:

go 1.22

use (
    ./my-service
    ./my-library
)

Now my-service automatically uses the local version of my-library without any replace directives. This is especially relevant when working with module resolution issues across multiple packages.

Note: Don’t commit go.work to your repository unless your team has agreed on a shared workspace layout. Add it to .gitignore for local development.

Still Not Working?

If none of the fixes above solved the error, try these less common solutions.

Clear the module cache

A corrupted module cache can cause bizarre resolution failures:

go clean -modcache
go mod tidy

This deletes everything in $GOPATH/pkg/mod/ and re-downloads all dependencies. It’s a clean slate.

Fix proxy issues (GOPROXY)

Check your proxy configuration:

go env GOPROXY

The default is https://proxy.golang.org,direct. If it’s set to something else (or off), reset it:

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

If the default proxy is blocked (corporate firewall, regional restrictions), try a mirror:

# Common in China
go env -w GOPROXY=https://goproxy.cn,direct

Or bypass the proxy entirely:

go env -w GOPROXY=direct

Fix checksum database errors

If you see:

verifying github.com/example/[email protected]: checksum mismatch

Delete go.sum and regenerate it:

rm go.sum
go mod tidy

If the error persists, the module’s contents may have genuinely changed (a re-tagged release, for instance). Use GONOSUMDB for that specific module:

go env -w GONOSUMDB=github.com/example/lib

Use replace directives for local development

If you’re developing a dependency locally and want to test changes without publishing, add a replace directive to go.mod:

replace github.com/yourcompany/shared-lib => ../shared-lib

The local path must contain its own go.mod. After testing, remove the replace directive before committing. For a cleaner approach across multiple modules, consider using go.work (Fix 8) instead.

For forks, point to the fork repository:

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

Check your Go version

Some modules require a minimum Go version. Verify yours:

go version

If a module’s go.mod declares go 1.22 and you’re running Go 1.20, the build will fail. Either update Go or pin an older version of the dependency. This is a common issue when working on older codebases, similar to encountering undefined variable errors after a language version upgrade.

Verify the module exists on pkg.go.dev

Search for the package at pkg.go.dev. If it doesn’t appear, the module path might be wrong, the repository might be private, or the module might have been deleted. Check the repository directly and verify the go.mod file at the root declares the module path you expect.

IDE showing errors but build succeeds

If go build works from the terminal but your IDE shows “cannot find package” errors, restart the language server:

• VS Code: Open Command Palette, run “Go: Restart Language Server”
• GoLand: File > Invalidate Caches > Invalidate and Restart

If the language server is outdated, update it:

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

This is unrelated to the actual build system — it’s a tooling sync issue. Your code compiles fine; the IDE just needs to catch up. A similar category of tooling mismatch occurs when type errors appear only in the editor but not during compilation.

Related: For the closely related “no required module provides package” variant with more edge cases, see Fix: no required module provides package. For module-level resolution failures, see Fix: Go Module Not Found.