# How to Fix Go Module Not Found

Go module not found errors occur when Go cannot locate a required package. This guide covers common causes and solutions.

Error Patterns

Module Not Found

```text go: module github.com/user/package: cannot find module go: cannot find module providing package github.com/user/package

package github.com/user/package is not in GOROOT ```

go.mod Missing

text
go: cannot find main module; see go help modules
go.mod file not found

Version Not Found

text
go: github.com/user/package@v1.2.3: no matching versions for query "v1.2.3"
go: github.com/user/package@latest: module github.com/user/package: no versions available

Common Causes

  1. 1.Missing go.mod file - Project not initialized as a Go module
  2. 2.Module not downloaded - Dependency not in local cache
  3. 3.Incorrect module path - Import path doesn't match module declaration
  4. 4.Private repository - Module requires authentication
  5. 5.Version doesn't exist - Specified version tag not found
  6. 6.GOPATH mode - Using old GOPATH instead of Go modules
  7. 7.Network/proxy issues - Cannot reach module repository

Diagnosis Steps

Step 1: Check go.mod Exists

bash
ls go.mod
cat go.mod

Step 2: Verify Module Declaration

bash
head -n 1 go.mod
# Should show: module your-module-path

Step 3: Check Go Environment

bash
go env GO111MODULE
go env GOPATH
go env GONOSUMDB
go env GOPROXY

Step 4: Verify Module Exists

```bash # Check if module exists on the registry curl -s https://proxy.golang.org/github.com/user/package/@v/list

# Or visit directly # https://pkg.go.dev/github.com/user/package ```

Solutions

Solution 1: Initialize Go Module

```bash # Create go.mod file go mod init github.com/youruser/yourproject

# This creates: # module github.com/youruser/yourproject # go 1.21 ```

Solution 2: Download Dependencies

```bash # Download all dependencies go mod download

# Or tidy up dependencies go mod tidy

# This downloads missing modules and removes unused ones ```

Solution 3: Fix Import Paths

Ensure import path matches the module's declared path:

```go // WRONG: Import path doesn't match module name // If go.mod declares: module github.com/myorg/mypackage import "mypackage/submodule" // Wrong

// CORRECT: Use full module path import "github.com/myorg/mypackage/submodule" ```

Solution 4: Enable Go Modules

```bash # Force module mode export GO111MODULE=on go mod tidy

# Or set globally go env -w GO111MODULE=on ```

Solution 5: Configure Proxy for Private Modules

```bash # For private repositories go env -w GOPRIVATE=github.com/yourorg/* go env -w GONOSUMDB=github.com/yourorg/*

# Or set for session export GOPRIVATE=github.com/yourorg/* export GONOSUMDB=github.com/yourorg/* ```

Solution 6: Add Missing Dependencies

```bash # Add specific dependency go get github.com/user/package@latest

# Or specific version go get github.com/user/package@v1.2.3

# Or from branch go get github.com/user/package@main ```

Solution 7: Use Replace Directive

For local development or forked packages:

```go // go.mod module yourproject

go 1.21

require github.com/user/package v1.0.0

replace github.com/user/package => ../local-package

// Or use a fork replace github.com/user/package => github.com/yourfork/package v0.0.0-20231201 ```

Solution 8: Fix Network/Proxy Issues

```bash # Use direct connection go env -w GOPROXY=direct

# Or use specific proxy go env -w GOPROXY=https://proxy.golang.org,direct

# For China (common proxy) go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,direct

# For corporate proxy export GOPROXY=https://proxy.company.com,direct ```

Solution 9: Handle Private Git Repositories

```bash # Configure git for private repos git config --global url."git@github.com:".insteadOf "https://github.com/"

# Then set GOPRIVATE go env -w GOPRIVATE=github.com/yourcompany/*

# For multiple private sources go env -w GOPRIVATE=github.com/yourcompany/*,gitlab.yourcompany.com/* ```

Solution 10: Use Vendor Directory

```bash # Create vendor directory go mod vendor

# Build using vendor go build -mod=vendor

# This ensures dependencies are locally available ```

Common Scenarios

Starting a New Project

bash
mkdir myproject
cd myproject
go mod init github.com/youruser/myproject
# Write your code
go mod tidy  # Download dependencies

Importing Local Package

```go // go.mod in parent directory module github.com/myorg/myproject

go 1.21

// In subdirectory main.go package main

import "github.com/myorg/myproject/internal/utils" // Correct path ```

Replacing Dependency

```go // go.mod module myproject

go 1.21

require ( github.com/original/package v1.0.0 )

replace github.com/original/package => github.com/myfork/package v0.0.0-20240101 ```

Using Specific Commit

bash
go get github.com/user/package@abc1234  # Specific commit hash

Debug Module Resolution

```bash # Verbose output go get -v github.com/user/package

# Debug mode go get -x github.com/user/package

# Check module graph go mod graph ```

Clearing Module Cache

```bash # Clear all cached modules go clean -modcache

# This forces fresh download of all modules ```

Update All Dependencies

```bash # Update to latest versions go get -u ./...

# Update only direct dependencies go get -u=direct ./...

# Then tidy go mod tidy ```

Prevention Tips

  1. 1.Always use go mod init when starting a new project
  2. 2.Run go mod tidy after adding imports
  3. 3.Check pkg.go.dev before importing to verify module exists
  4. 4.Use version tags for stable releases
  5. 5.Configure GOPRIVATE for private repositories
bash
# Good practice: check module before import
go list -m github.com/user/package
  • go: cannot find main module - go.mod missing
  • go: module version mismatch - Version conflict
  • build constraints exclude all files - Platform-specific code