How to Resolve "Cannot Find Package" Error in Go Modules

Your Go build fails because the compiler can't locate a package you're importing, even though you're fairly sure it exists. In modern Go this almost always traces back to a mismatch between your import path and what go.mod and the module cache actually know about.

The Problem

Running go build or go run fails immediately with a missing package error:

$ go build .
main.go:5:2: cannot find package "github.com/youruser/yourrepo/internal/utils" in any of:
	/usr/local/go/src/github.com/youruser/yourrepo/internal/utils (from $GOROOT)
	/home/user/go/src/github.com/youruser/yourrepo/internal/utils (from $GOPATH)

With Go modules, the error is more often phrased slightly differently:

$ go build .
main.go:5:2: no required module provides package github.com/youruser/yourrepo/internal/utils; to add it:
	go get github.com/youruser/yourrepo/internal/utils

Or, for a genuinely external dependency:

go: github.com/some/package@v1.4.0: reading github.com/some/package/go.mod at revision v1.4.0: unknown revision v1.4.0

Why It Happens

Since Go 1.16+, Go modules are the default and expect a consistent module path declared in go.mod that matches how you import your own internal packages. The error appears for a handful of distinct reasons:

• The module name in go.mod doesn't match the import paths used in your code, so Go can't resolve internal packages to their actual location on disk.
• You added an import statement for a package you haven't run go get for yet, so it's missing from go.mod and go.sum.
• You're running commands from outside the module root, or there's no go.mod file at all in the project.
• The dependency's version tag doesn't actually exist on the remote (a typo in the version, or the maintainer deleted/renamed a tag).
• Your network can't reach the Go module proxy (proxy.golang.org) due to a firewall, VPN, or misconfigured GOPROXY.
• A private repository dependency isn't authenticated, so Go can't fetch it at all.

The Fix

First, confirm you actually have a go.mod file and check what module name it declares:

cat go.mod

module github.com/youruser/yourrepo

go 1.22

Every internal import in your code needs to start with exactly that module path. If your import says github.com/youruser/yourrepo/internal/utils, the file needs to physically live at internal/utils/ relative to the module root, and the module declaration has to match. If it doesn't match, fix the module line or your import paths so they agree.

For external packages that are genuinely missing from go.mod, add them explicitly:

go get github.com/some/package@latest

Then clean up and verify the module files are consistent:

go mod tidy

This adds anything missing, removes anything unused, and rewrites go.sum to match. Rebuild:

go build ./...

If the issue is a proxy or network problem, check your current GOPROXY setting:

go env GOPROXY

The default should be https://proxy.golang.org,direct. If it's misconfigured or blocked by a corporate firewall, reset it:

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

For private repositories, tell Go which module paths to fetch directly via Git instead of the public proxy, and make sure your Git credentials are configured:

go env -w GOPRIVATE=github.com/yourorg/*
git config --global url."git@github.com:".insteadOf "https://github.com/"

Still Not Working?

If go mod tidy succeeds but the build still fails, clear the module cache and try a completely clean fetch — a corrupted local cache entry can cause persistent, confusing errors:

go clean -modcache
go mod download
go build ./...

If you're inside a monorepo with multiple go.mod files, double-check you're running go build from the correct module's directory — Go modules don't automatically nest, and running a command from the wrong subdirectory produces exactly this kind of "cannot find package" error even when everything is configured correctly one level up.

It also helps to understand the difference between go.mod and go.sum, since errors sometimes come from a stale or mismatched go.sum rather than go.mod itself. go.sum records cryptographic checksums for every dependency version your module has ever referenced, and if it's out of sync with go.mod — commonly after a manual edit or a bad merge — Go can refuse to build with a checksum mismatch that looks superficially similar to a missing package:

go: github.com/some/package@v1.4.0: checksum mismatch
	downloaded: h1:abc...
	go.sum:     h1:xyz...

If you're confident the dependency itself hasn't been tampered with and the mismatch is just from a merge conflict or manual edit, regenerate go.sum cleanly:

rm go.sum
go mod tidy

Finally, if you're working with Go workspaces (go.work) across multiple local modules, confirm the workspace file actually references the module you're trying to build from, since a missing use directive will cause Go to fall back to remote resolution for a package that actually lives right there on disk:

cat go.work

go 1.22

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