Fix Go Module Version Mismatch Not Found

What's Actually Happening

Your Go project fails to build because module versions are mismatched or dependencies cannot be found. The go build or go run commands fail with errors indicating that required packages don't exist, versions don't match, or the Go toolchain cannot resolve the correct version of a dependency.

This typically happens when go.mod specifies a version that doesn't exist, when there are transitive dependency conflicts, when using pseudo-versions that have been replaced, or when the module proxy cannot find the requested version. The build process stops and you cannot compile or run your application.

The Error You'll See

```bash # Version not found go: github.com/user/package@v1.2.3: reading github.com/user/package/go.mod at revision v1.2.3: unknown revision

# Version mismatch go: github.com/user/package@v1.0.0: missing go.sum entry for go.mod file; to add it: go mod download github.com/user/package

# Inconsistent versions go: inconsistent vendoring in /path/to/project: go.mod: github.com/user/package@v1.2.0 vendor/modules.txt: github.com/user/package@v1.1.0

# Pseudo-version issues go: github.com/user/package@v0.0.0-20240101000000-abcdef123456: invalid pseudo-version: does not match version-control timestamp (got 20231231000000)

# Replacement errors go: github.com/user/package@v1.0.0: replacement directory ./local/package does not exist

# Indirect dependency issues go: github.com/indirect/package@v2.0.0: missing go.sum entry; to add it: go mod download github.com/indirect/package

# Version conflict go: github.com/user/package: module github.com/user/package@latest found (v1.5.0), but does not contain package github.com/user/package/subpkg

# Minimum version issues go: module github.com/user/package requires Go 1.21 but current Go version is 1.20 ```

Why This Happens

1. 1.Version doesn't exist: go.mod references a version tag that was deleted or never existed.
2. 2.Transitive dependency conflicts: Different modules require incompatible versions of the same dependency.
3. 3.Pseudo-version mismatch: The pseudo-version in go.mod doesn't match the actual commit timestamp or hash.
4. 4.Module not published: The package exists but wasn't published as a Go module (no go.mod in repo).
5. 5.Proxy/cache issues: Go module proxy returns cached errors or the proxy is unavailable.
6. 6.Import path changes: The module moved to a different path but go.mod has the old path.
7. 7.Vendor directory out of sync: go.mod updated but vendor directory wasn't updated.
8. 8.Local replace paths: Replace directives point to paths that don't exist or moved.
9. 9.Go version incompatibility: Module requires a newer Go version than installed.
10. 10.Private modules: Private repositories not configured in GOPRIVATE.

Step 1: Diagnose the Problem

Identify what's causing the issue:

```bash # Check go.mod for issues cat go.mod

# Check go.sum for consistency cat go.sum | grep "problematic-package"

# Verify module exists go list -m -versions github.com/user/package

# Check all versions go list -m -versions -json github.com/user/package

# Check what's in go.sum grep "github.com/user/package" go.sum

# Verify specific version exists go mod download github.com/user/package@v1.2.3

# Check graph of dependencies go mod graph | grep "problematic-package"

# Check why a package is needed go mod why github.com/user/package

# Check for updates go list -u -m all

# Check module info go mod edit -json

# Verify Go version go version

# Clean module cache go clean -modcache

# Verify GOPROXY go env GOPROXY go env GOSUMDB go env GOPRIVATE ```

Step 2: Fix Version Not Found

Resolve missing version errors:

```bash # List available versions go list -m -versions github.com/user/package

# Use latest version go get github.com/user/package@latest

# Use specific version that exists go get github.com/user/package@v1.2.0

# Update to compatible version go get github.com/user/package

# Edit go.mod directly go mod edit -require=github.com/user/package@v1.2.0

# If using replace directive go mod edit -replace=github.com/user/package=github.com/other/package@v1.0.0

# Fix by removing and re-adding go mod edit -droprequire=github.com/user/package go get github.com/user/package@v1.2.0

# Check if module exists curl -s "https://proxy.golang.org/github.com/@latest" | jq .

# For private modules export GOPRIVATE=github.com/your-org/* go get github.com/your-org/private-package@v1.0.0 ```

Step 3: Fix Version Mismatches

Resolve version conflicts:

```bash # Update all dependencies go get -u ./...

# Update specific package go get github.com/user/package@v1.2.0

# Tidy up go.mod go mod tidy

# Download missing modules go mod download

# Verify dependencies go mod verify

# Check for indirect dependencies issues go mod why -m github.com/indirect/package

# Force specific version go get github.com/user/package@v1.2.0 go mod tidy

# Handle major version differences # v2+ must have /v2 in import path go get github.com/user/package/v2@latest

# Update go.sum rm go.sum go mod tidy

# Fix using minimal version selection go mod tidy -go=1.21

# Use replace for incompatible versions go mod edit -replace=github.com/user/package=github.com/user/package@v1.2.0 ```

Step 4: Fix go.mod and go.sum Consistency

Ensure go.mod and go.sum are in sync:

```bash # Clean up go.mod go mod tidy

# Remove unused dependencies go mod tidy -v

# Download all dependencies go mod download

# Verify checksums go mod verify

# Fix vendor directory go mod vendor rm -rf vendor go mod vendor

# Check for duplicates in go.sum sort go.sum | uniq -d

# Remove and regenerate go.sum rm go.sum go mod download go mod tidy

# Fix indirect dependencies go mod edit -droprequire=github.com/unnecessary/package go mod tidy ```

Step 5: Handle Pseudo-Versions

Fix pseudo-version issues:

```bash # Pseudo-version format: v0.0.0-yyyymmddhhmmss-abcdefabcdef

# Update to actual version if available go get github.com/user/package@latest

# Get pseudo-version from commit git ls-remote https://github.com/user/package.git <commit-hash>

# Update pseudo-version go get github.com/user/package@<commit-hash>

# Fix mismatched pseudo-version go get github.com/user/package@<correct-commit>

# Use branch name instead go get github.com/user/package@main go get github.com/user/package@master

# Check available refs git ls-remote https://github.com/user/package.git

# Generate correct pseudo-version cd $(mktemp -d) git clone https://github.com/user/package.git cd package git log -1 --format="%H %ct" <commit> # Format: <commit-hash> <unix-timestamp>

# Update in go.mod go mod edit -require=github.com/user/package@v0.0.0-20240101120000-abcdef123456 go mod tidy ```

Step 6: Fix Replace Directives

Correct replacement paths:

```go // go.mod - Fix replace directives

// Local directory replacement replace github.com/user/package => ./local/package

// Different module replacement replace github.com/user/package => github.com/other/package v1.0.0

// Specific version replacement replace github.com/user/package v1.0.0 => github.com/user/package v1.1.0

// Fork replacement replace github.com/original/package => github.com/yourfork/package v0.0.0-20240101000000-abcdef123456 ```

```bash # Add replace directive go mod edit -replace=github.com/user/package=./local/package

# Drop replace directive go mod edit -dropreplace=github.com/user/package

# Verify replacement go list -m github.com/user/package

# Fix path for local replacement # Ensure the path exists and contains go.mod ls ./local/package/go.mod

# If local package doesn't have go.mod, create one cd ./local/package go mod init github.com/user/package ```

Step 7: Handle Private Modules

Configure access to private repositories:

```bash # Set GOPRIVATE for private modules export GOPRIVATE=github.com/your-org/*,gitlab.com/your-org/*

# Or in go env go env -w GOPRIVATE=github.com/your-org/*

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

# For multiple private hosts git config --global url."git@gitlab.com:".insteadOf "https://gitlab.com/"

# Skip checksum verification for private modules export GONOSUMDB=github.com/your-org/* go env -w GONOSUMDB=github.com/your-org/*

# Use direct connection for private modules export GOPRIVATE=github.com/your-org/* export GONOPROXY=github.com/your-org/* export GONOSUMDB=github.com/your-org/*

# For corporate proxies export GOPROXY=https://proxy.golang.org,https://your-corp-proxy.com,direct

# Test private module access go get github.com/your-org/private-package@latest

# Use .netrc for authentication cat > ~/.netrc << EOF machine github.com login your-username password your-token EOF chmod 600 ~/.netrc ```

Step 8: Fix Go Version Incompatibility

Handle Go version issues:

```bash # Check current Go version go version

# Check required Go version cat go.mod | grep "go "

# Update go.mod Go version go mod edit -go=1.21

# If module requires newer Go, update Go # Use official installer or version manager

# Or downgrade module requirement go get github.com/user/package@v1.0.0 # Version compatible with your Go

# Check toolchain go env GOTOOLCHAIN go env -w GOTOOLCHAIN=auto # Let Go manage toolchain

# Use specific toolchain GOTOOLCHAIN=go1.21.0 go build

# Fix go.mod directive go mod edit -go=1.20.0 go mod tidy

# For compatibility, use older syntax //go:build go1.21 // Remove if using older Go ```

Step 9: Clean and Rebuild

Start fresh when all else fails:

```bash # Clean module cache go clean -modcache

# Remove go.sum rm go.sum

# Remove vendor directory rm -rf vendor/

# Remove go.work if exists rm go.work go.work.sum

# Download dependencies fresh go mod download

# Tidy go.mod go mod tidy

# Verify modules go mod verify

# Rebuild vendor if used go mod vendor

# Test build go build ./...

# Run tests go test ./...

# Full reset rm -rf $GOPATH/pkg/mod rm go.sum go mod tidy go mod download ```

Step 10: Create Diagnostic Script

Build troubleshooting tool:

```bash #!/bin/bash # diagnose_go_module.sh

PACKAGE=${1:-""}

echo "=== Go Module Diagnostics ===" echo ""

echo "1. Go Version" echo "-------------" go version echo ""

echo "2. Go Environment" echo "-----------------" go env GOPROXY GOSUMDB GOPRIVATE GOTOOLCHAIN echo ""

echo "3. go.mod Contents" echo "------------------" cat go.mod echo ""

echo "4. Problem Package in go.sum" echo "----------------------------" if [ -n "$PACKAGE" ]; then grep "$PACKAGE" go.sum fi echo ""

echo "5. Available Versions" echo "--------------------" if [ -n "$PACKAGE" ]; then go list -m -versions $PACKAGE 2>&1 | head -5 fi echo ""

echo "6. Dependency Graph" echo "------------------" if [ -n "$PACKAGE" ]; then go mod graph | grep "$PACKAGE" | head -10 fi echo ""

echo "7. Why Package is Needed" echo "------------------------" if [ -n "$PACKAGE" ]; then go mod why $PACKAGE fi echo ""

echo "8. Module Verification" echo "---------------------" go mod verify 2>&1 | head -10 echo ""

echo "9. Download Status" echo "-----------------" if [ -n "$PACKAGE" ]; then go mod download $PACKAGE 2>&1 fi echo ""

echo "10. Build Test" echo "-------------" go build ./... 2>&1 | head -20 echo ""

echo "=== Diagnostics Complete ===" ```

Checklist

Verify the Fix

1. 1.Build successfully:
2. 2.```bash
3. 3.go build ./...
4. 4.`
5. 5.Run tests:
6. 6.```bash
7. 7.go test ./...
8. 8.`
9. 9.Verify modules:
10. 10.```bash
11. 11.go mod verify
12. 12.`

Related Issues

• [Fix Go Build Cannot Find Package](/articles/fix-go-build-cannot-find-package)
• [Fix Go Get Connection Refused](/articles/fix-go-get-connection-refused)
• [Fix Go Import Cycle Not Allowed](/articles/fix-go-import-cycle-not-allowed)
• [Fix Go Mod Download Failed](/articles/fix-go-mod-download-failed)
• [Fix Go Vendor Out of Sync](/articles/fix-go-vendor-out-of-sync)