no required module provides package X; to add it: go get X

The exact error string

$ go build ./...
main.go:5:2: no required module provides package github.com/lib/pq; to add it:
	go get github.com/lib/pq

// or, on an older Go toolchain / different code path:
go: cannot find module providing package github.com/lib/pq

// and if there is no go.mod at all, the same line carries a different tail:
main.go:3:1: no required module provides package github.com/lib/pq: go.mod file
not found in current directory or any parent directory; see 'go help modules'

What it actually looks like

All three shapes describe the same underlying failure — the resolution process below never located a module for the imported path — but the modern form tells you the fix inline. One detail worth pinning down, because it trips people searching for the message: the suggestion Go prints is always go get <path>, never go mod tidy. Verified on go1.23.12, where go build, go run, go test and go vet all emit the identical to add it: go get <path> line. go mod tidy remains an excellent fix — it sweeps every unresolved import at once rather than one at a time — it just isn't what the compiler suggests.

The module resolution walk, visually

Cause 1: the import is new and genuinely just missing from go.mod

// you just added this import, but never ran a get/tidy step:
import "github.com/lib/pq"

// ❌ go.mod has no matching require line yet — stage 1 fails immediately

// ✅ let Go resolve it and update go.mod + go.sum for you:
go get github.com/lib/pq
// or, to resolve every unresolved import in the whole module at once:
go mod tidy

This is the overwhelming majority case, and it's a normal, expected part of adding a new dependency — Go's module system requires every dependency to be explicitly recorded in go.mod (with a specific version) before it can be resolved, rather than implicitly trusting whatever happens to be importable. Writing the import line in your source is necessary but not sufficient; go get or go mod tidy performs the separate step of actually recording that dependency and its resolved version.

Cause 2: a typo or wrong path segment in the import string

// ❌ extra or wrong path segment — this exact string has no
//    corresponding module, so all three resolution stages fail:
import "github.com/gorilla/mux/v2"

// ✅ match the module's actual, published import path exactly
//    (check the module's own go.mod / README for the correct one):
import "github.com/gorilla/mux"

Unlike a typo in a local identifier (which produces an "undefined" error after successful compilation of the surrounding file), a typo'd import path fails at a much earlier stage — the module resolution machinery itself, before your code is even type-checked. Because module paths often mirror a hosting URL, it's tempting to assume "it exists on GitHub" guarantees resolvability, but Go matches the import string exactly against a module's declared path; an extra version suffix, a wrong case, or a subdirectory that isn't itself a separate module all produce this identical error.

Cause 3: a private repository the tool can't authenticate against

# tell Go this module path is private, so it skips the public
# checksum database (sum.golang.org) and proxy (proxy.golang.org)
# for it, going straight to the source instead:
go env -w GOPRIVATE=github.com/mycompany/*

# then make sure the underlying fetch (git over https) can actually
# authenticate — e.g. via a configured git credential helper or a
# .netrc entry for your private host

By default, Go resolves modules through the public module proxy and verifies them against the public checksum database — neither of which has any way to see a private repository, so the network stage fails exactly as if the module didn't exist anywhere. Setting GOPRIVATE (or the more granular GONOSUMCHECK/GOFLAGS equivalents) tells Go to bypass the public infrastructure for matching paths and fetch directly via the underlying version control tool, which then needs its own working authentication (SSH key, a git credential helper, or a .netrc entry) completely independent of Go itself.

Cause 4: an empty local cache — the classic "works on my machine, fails in CI"

# confirm what's actually cached locally vs. what a clean
# environment (like CI) would see:
go env GOMODCACHE
ls $(go env GOMODCACHE)/github.com/

# reproduce the CI failure locally by clearing the cache first:
go clean -modcache
go build .   # now this machine behaves like a fresh CI runner

A developer's machine accumulates a populated module cache over weeks or months of work, so a dependency that was fetched once loads instantly from disk on every subsequent build — masking network or authentication problems entirely. A CI runner typically starts with an empty cache every run (unless explicitly configured to persist one), so it must actually execute the network-fetch stage from scratch; if that stage is the one that's broken (a blocked outbound connection, an unconfigured private-module credential, a proxy unreachable from the CI network specifically), the exact same import that "just works" locally fails reliably in CI.

Common causes at a glance

Debugging checklist

• ✓ Run go mod tidy first — it resolves the majority of cases in one step
• ✓ Double-check the import path against the module's own published path (README, its own go.mod)
• ✓ If it's an internal/private module, confirm GOPRIVATE is set and git auth actually works
• ✓ Reproduce a CI-only failure locally with go clean -modcache before assuming it's environment-specific magic
• ✓ Check go env GOPROXY if your network requires a specific internal proxy

References

• Go Modules Reference (go.dev)
• Managing dependencies (go.dev)