Introduction

Go modules manage dependencies through go.mod and go.sum files, but version conflicts arise when indirect dependencies require incompatible versions, when go.sum gets corrupted, or when replace directives create inconsistent module graphs. The error module requires toolchain or go.mod has non-... module path blocks builds and the fix requires understanding Go's minimal version selection (MVS) algorithm, which picks the highest version of each dependency required by any path in the module graph.

Symptoms

bash
go: github.com/example/pkg@v1.2.3: missing go.sum entry for go.mod file; to add it:
    go mod download github.com/example/pkg

Or:

bash
go mod tidy: github.com/foo/bar@v2.0.0: parsing go.mod:
    module declares its path as: github.com/foo/baz
    but was required as: github.com/foo/bar

Or:

bash
go: github.com/example@v1.0.0 requires go >= 1.21 (running go 1.20)

Common Causes

  • Corrupted go.sum: Checksums do not match downloaded modules
  • Module path mismatch: Module declares different path than import path
  • Indirect dependency conflict: Two dependencies require different versions of same module
  • Replace directive conflict: Replace creates version that other deps do not accept
  • Go version incompatibility: Dependency requires newer Go than available
  • Vendor directory out of sync: go.mod updated but vendor not refreshed

Step-by-Step Fix

Step 1: Clean up module state

```bash # Clear module cache and re-download go clean -modcache go mod download

# Tidy and verify go mod tidy go mod verify

# If go.sum is corrupted rm go.sum go mod tidy ```

Step 2: Resolve version conflicts

```bash # Show why a dependency is required go mod why github.com/example/pkg

# Show dependency graph go mod graph | grep example

# Update specific dependency go get github.com/example/pkg@v1.3.0

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

# Downgrade a dependency go get github.com/example/pkg@v1.2.0 ```

Step 3: Fix replace directives

```go // go.mod module github.com/myorg/myapp

go 1.21

require ( github.com/gin-gonic/gin v1.9.1 github.com/example/pkg v1.2.3 )

// Replace with local fork (for development) replace github.com/example/pkg => ../local-pkg

// Replace with specific version replace github.com/example/pkg => github.com/example/pkg v1.3.0

// After changing replace directives go mod tidy go build ./... ```

Prevention

  • Run go mod tidy after every dependency change
  • Commit both go.mod and go.sum together
  • Use go mod verify in CI to check module integrity
  • Avoid replace directives in published modules -- they are ignored by consumers
  • Pin dependency versions explicitly rather than relying on indirect resolution
  • Use go get -u regularly to stay current with security patches
  • Add a CI step that runs go mod tidy and fails if go.mod changes