How to Fix Go 'module not found' Error

In this tutorial, you'll learn about How to Fix Go 'module not found' Error. We cover key concepts, practical examples, and best practices.

The Problem

You run go build or go run and get:

main.go:5:2: module github.com/gin-gonic/gin: no matching versions for query "latest"
main.go:6:2: module example.com/mypackage: no matching versions for query "v1.0.0"

Go modules can't be found when imports don't match available versions, the module proxy is unreachable, or the go.mod file is incomplete. The error message tells you exactly which module and version are missing — read it carefully before running other commands.

Quick Fix

1. Initialize or update go.mod

go mod init github.com/user/myproject
go mod tidy

go mod init creates a new go.mod file. go mod tidy adds missing module requirements and removes unused ones. This is the first command to run for any missing-module error.

2. Set GOPROXY for environments behind a firewall

go env -w GOPROXY=https://goproxy.cn,direct

If you're in China or behind a corporate firewall, the default proxy (proxy.golang.org) may be blocked. Use goproxy.cn or goproxy.io as alternatives. The ,direct fallback tries the source if the proxy fails.

3. Download the missing module explicitly

go get github.com/gin-gonic/gin@latest

Expected output:

go: added github.com/gin-gonic/gin v1.10.0

go get downloads a specific module and updates go.mod and go.sum.

4. Clear the module cache

go clean -modcache
go mod download

Corrupted downloads in $GOPATH/pkg/mod/cache cause "module not found" errors even when the module exists. Clearing the cache forces a fresh download.

5. Verify module path matches import path

Check that the module path in go.mod matches the import path in your source code:

head -1 go.mod
# Output: module github.com/user/myproject

// In main.go — must match the module path
import "github.com/user/myproject/pkg"

A mismatch between module in go.mod and the import statement is the most common cause of "not found" errors for local packages.

6. Configure private repositories

# If your module is in a private repo
go env -w GOPRIVATE=github.com/mycompany/*

# Or for self-hosted repos
go env -w GONOSUMCHECK=gitlab.internal/*
go env -w GONOSUMDB=gitlab.internal/*

Private repos need GOPRIVATE to bypass the module proxy and checksum database. Without this, Go tries to fetch from the proxy (which can't access private repos) and fails.

7. Use replace directives for local development

// go.mod — replace a module with a local path
replace github.com/user/shared-lib => ../shared-lib

Use replace when developing multiple modules locally. It redirects Go to a local directory instead of downloading from the remote.

8. Check Go version requirements

go version
cat go.mod | grep "^go "

Expected output:

go version go1.22.2 linux/amd64
go 1.21

Some modules require a minimum Go version. If go.mod says go 1.22 but you have go 1.20, upgrade Go or find a compatible module version.

Prevention

• Run go mod tidy after every import change
• Commit go.mod and go.sum to version control
• Set GOPROXY correctly in CI/CD environments
• Use go env -w GOPRIVATE for private repositories
• Pin module versions in go.mod for reproducible builds
• Check with go version that your Go version meets the module's minimum requirement
• Use go mod download before go build in CI to separate dependency errors from build errors