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

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

Both message shapes describe the same underlying failure — the resolution process below never located a module for the imported path — but the newer, friendlier form actually tells you the fix inline (go get for the specific missing module, or go mod tidy for a broader sweep of every unresolved import in the project).

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