Fix "go: module not found" Error in Go Modules

The Error

You run go build, go run, or go get, and hit:

go: module not found

Sometimes it comes with more context:

go: github.com/some/package@v1.2.3: reading https://proxy.golang.org/github.com/some/package/@v/v1.2.3.info: 404 Not Found
go: module not found

Go can't find the module — not in your local cache, not on the proxy, or your go.mod is misconfigured. Usually one of seven things is to blame.

Why This Happens

The causes vary more than you'd expect:

No go.mod in your project root, or you're running Go commands outside the module directory
The module path in go.mod doesn't match what your code actually imports
The package version you specified doesn't exist — the tag was never pushed, or it was deleted
GO111MODULE=off is set, so Go ignores go.mod entirely and falls back to GOPATH mode
A private module that the public proxy at proxy.golang.org can't reach
A replace directive pointing to a local path that no longer exists
A corrupted or incomplete module cache

Fixes

1. Make sure you're inside a Go module

Check whether go.mod exists in your project root:

ls go.mod

No file? Initialize one:

go mod init github.com/yourname/yourproject

Then pull in all required dependencies:

go mod tidy

2. Confirm the module path matches your imports

Open go.mod and check the first line:

module github.com/yourname/yourproject

go 1.21

Here's a common trap: your code imports github.com/yourname/yourproject/utils, but go.mod declares the module as myapp. Go sees two different module paths and fails. Fix the module line to match exactly what your import statements use.

3. Check GO111MODULE

Module mode has been the default since Go 1.16. That said, if someone set GO111MODULE=off in the environment — maybe on an older CI machine — Go silently ignores your go.mod.

go env GO111MODULE

If it's off, fix it:

# Linux/macOS
export GO111MODULE=on

# Windows (PowerShell)
$env:GO111MODULE = "on"

Or just clear it to use the default:

go env -w GO111MODULE=

4. Fetch the missing module directly

If a specific package is absent, add it explicitly:

go get github.com/some/package@latest

Pin to a specific release if you need one:

go get github.com/some/package@v1.2.3

Always run go mod tidy afterward to keep go.mod and go.sum consistent:

go mod tidy

5. Check for broken replace directives

A replace block in go.mod that points to a missing local path will cause this error every time:

replace github.com/some/package => ../local-fork

Run ls ../local-fork to confirm the directory exists. If the path moved, update it. If you no longer need the override, delete the directive.

6. Handle private modules

The public proxy can't reach private repos — GitHub Enterprise, GitLab self-hosted, Gitea, and similar. Tell Go to skip the proxy for your private domain:

go env -w GOPRIVATE=gitlab.company.com/*
go env -w GONOSUMCHECK=gitlab.company.com/*

After this, Go fetches those modules directly from the source instead of going through proxy.golang.org. You'll also need your SSH key or a ~/.netrc entry for authentication.

7. Wipe the module cache

A partial download can corrupt the cache and block future fetches. Clear it:

go clean -modcache
go mod download

On a busy project this might re-download a few hundred megabytes, but it's the fastest way to rule out cache issues.

Verify the Fix

Check that all modules resolve cleanly:

go mod verify

Expected output:

all modules verified

Then do a full build:

go build ./...

Clean output means you're done. To inspect where a specific dependency is coming from:

go mod graph | grep some/package

Quick Diagnostic Checklist

No go.mod? → Run go mod init
Module path mismatch? → Fix the module line in go.mod
GO111MODULE=off? → Unset it or set to on
Version doesn't exist? → Check the repo's tags, use @latest
Private repo? → Set GOPRIVATE for your domain
Broken replace directive? → Verify the path or remove the directive
Stale cache? → go clean -modcache

Just Cloned the Repo?

If you cloned a project and hit this error immediately, run go mod download before building. It pulls every dependency listed in go.sum into your local cache — the Go equivalent of npm install.

git clone https://github.com/example/repo
cd repo
go mod download
go build ./...

Most "module not found" errors on fresh clones disappear after this one step.