}

Fix: Golang "compile version does not match go tool version" & Related Errors (2026)

Last updated: 10 min read

Fix: compile: version does not match go tool version

The "compile: version does not match go tool version" error — and its related siblings — are among the most common Go programming issues. They almost always trace back to having multiple Go versions installed, a mismatched go.mod directive, or a broken module cache. This guide covers every scenario with step-by-step fixes.

The Error Messages

compile: version does not match go tool version

compile: version "go1.21" does not match go tool version "go1.22"

Or with a specific package:

go get -u github.com/some/package
compile: version "go1.9" does not match go tool version "go1.9.2"

The error means your Go compiler binary (go) and the Go toolchain it references internally are from different installations and do not agree on the version.

command-line-arguments runtime.main_main·f: function main is undeclared in the main package

This error appears during go build or go run and looks like:

# command-line-arguments
runtime.main_main·f: function main is undeclared in the main package

What causes it: The compiler resolved the wrong runtime package — usually because GOROOT points to a different Go installation than the go binary on your PATH. The runtime package it found was compiled for a different Go version and the linker cannot reconcile the mismatch.

Step-by-step fix:

  1. Find which go binary is active:
which go
go version
  1. Find what GOROOT is set to:
go env GOROOT
  1. They must agree. If which go returns /opt/homebrew/bin/go but GOROOT is /usr/local/go, you have a conflict. Fix it:
# For Homebrew on Apple Silicon
export GOROOT=$(brew --prefix go)/libexec
export PATH=$GOROOT/bin:$PATH
source ~/.zshrc
  1. Clear cached build artifacts that reference the old runtime:
go clean -cache
go clean -modcache
  1. Rebuild:
go build ./...

go: inconsistent vendoring

The full error looks like:

go: inconsistent vendoring in /path/to/project:
        github.com/some/[email protected]: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt

        To ignore the vendor directory, use -mod=mod.

What causes it: The vendor/ directory is out of sync with go.mod and go.sum. This typically happens after:

  • Manually editing go.mod
  • Pulling changes that updated go.mod without re-running go mod vendor
  • Upgrading Go to a version with stricter vendoring checks (Go 1.14+)

Step-by-step fix:

  1. Re-generate the vendor directory from go.mod:
go mod tidy
go mod vendor
  1. Verify the vendor directory is now consistent:
go mod verify
  1. If you want to skip the vendor directory entirely for a single build:
go build -mod=mod ./...
  1. If the project should not use vendoring at all, remove the directory:
rm -rf vendor/
go mod tidy

build constraints exclude all Go files

The full error:

pattern ./...: directory prefix . has no Go files

Or more specifically:

[no Go files in /path/to/package]
build constraints exclude all Go files in /path/to/package

What causes it: Go's build tag system is filtering out all .go files in a package because none match the current Go version, OS, or architecture. This commonly happens when:

  • The package requires a minimum Go version (//go:build go1.21) higher than your installed version
  • You are building for the wrong OS or architecture
  • A file uses //go:build ignore intentionally

Step-by-step fix:

  1. Check the Go version required by the module:
head -5 go.mod
# go 1.22

Compare with your installed version:

go version

If your Go version is older than the go directive in go.mod, upgrade Go (see the version management section below).

  1. Check the build tags at the top of the problematic .go files:
head -3 path/to/file.go
# //go:build go1.22
  1. To build explicitly for a specific OS/arch combination:
GOOS=linux GOARCH=amd64 go build ./...
  1. To list which files would be included under current constraints:
go list -f '{{.GoFiles}}' ./...
go list -f '{{.IgnoredGoFiles}}' ./...

Why These Errors Happen

1. Multiple Go Installations

The most common root cause — Go is installed via multiple methods simultaneously:

  • Homebrew (brew install go)
  • Official installer (.tar.gz or .pkg from golang.org)
  • A version manager (goenv, gvm, asdf)

Each installs its own go binary and runtime, and PATH ordering determines which one runs.

2. Incorrect GOROOT

GOROOT points to a different Go installation than the go binary on your PATH.

3. Stale Compiled Tools

After updating Go, old compiled tools in $GOPATH/bin or $GOBIN may reference the previous version.

4. go.mod Version Directive Mismatch

The go directive in go.mod specifies the minimum Go version for the module. If your installed Go is older, builds may fail with constraint or toolchain errors.

5. IDE Using a Different Go Version

VS Code or GoLand may be configured to use a different Go installation than your terminal. See the IDE-specific section below.

How to Check Go Version and Module Requirements

Check installed Go version

go version
# go version go1.22.3 linux/amd64

Check environment variables

go env GOVERSION
go env GOROOT
go env GOPATH
go env GOBIN

Check what go.mod requires

# View the module name and Go version directive
head -5 go.mod

# List all direct and indirect dependencies
go list -m all

# Check for available updates
go list -m -u all

Clean up and sync the module graph

# Remove unused dependencies and add missing ones
go mod tidy

# Verify all cached modules match their checksums
go mod verify

# Show the full module dependency graph
go mod graph

Solution 1: Remove Duplicate Go Installations (Recommended)

Keep only one Go installation on the system.

On macOS

# Check which Go is active
which go
go version

# Remove Homebrew Go
brew uninstall go

# Or remove the official installation
sudo rm -rf /usr/local/go

# Remove any stale PATH entries from ~/.bashrc or ~/.zshrc
# Delete or comment out lines like:
# export PATH=$PATH:/usr/local/go/bin
source ~/.zshrc

On Linux

# Check installed Go
which go
go version

# Remove apt/yum-installed Go (Debian/Ubuntu)
sudo apt remove golang-go && sudo apt autoremove

# Or remove a manually installed Go
sudo rm -rf /usr/local/go
sed -i '/\/usr\/local\/go\/bin/d' ~/.bashrc
source ~/.bashrc

On Windows

  1. Open "Add or Remove Programs"
  2. Uninstall all Go versions you do not need
  3. Check and clean these directories: C:\Go, C:\Program Files\Go
  4. Remove Go bin directories from the PATH environment variable

Solution 2: Fix Environment Variables

# If using official installation
export GOROOT=/usr/local/go
export PATH=$GOROOT/bin:$PATH

# If using Homebrew on Apple Silicon
export GOROOT=$(brew --prefix go)/libexec
export PATH=$GOROOT/bin:$PATH

# If using Homebrew on Intel Mac
export GOROOT=/usr/local/opt/go/libexec
export PATH=$GOROOT/bin:$PATH

Reload your shell and verify:

source ~/.zshrc   # or ~/.bashrc
which go
go version
go env GOROOT

All three outputs must reference the same Go installation.

Solution 3: Clear Go Module Cache and Rebuild Tools

Stale compiled artifacts from an old Go version can cause phantom version mismatches:

# Clear the build cache
go clean -cache

# Clear the module download cache
go clean -modcache

# Reinstall common tools
go install golang.org/x/tools/...@latest
go install github.com/go-delve/delve/cmd/dlv@latest

Solution 4: Managing Multiple Go Versions with goenv or asdf

If you genuinely need multiple Go versions for different projects, use a dedicated version manager instead of manual parallel installations.

Using goenv

goenv works similarly to pyenv or rbenv — it installs Go versions in ~/.goenv/versions/ and switches between them using shims.

# Install goenv
git clone https://github.com/syndbg/goenv.git ~/.goenv

# Add to ~/.bashrc or ~/.zshrc
export GOENV_ROOT="$HOME/.goenv"
export PATH="$GOENV_ROOT/bin:$PATH"
eval "$(goenv init -)"

# Apply immediately
source ~/.zshrc

# Install specific versions
goenv install 1.21.13
goenv install 1.22.5
goenv install 1.23.4
goenv install 1.24.0

# Set a global default
goenv global 1.22.5

# Set a per-project version (creates .go-version file)
cd my-project
goenv local 1.21.13

# Verify
go version

Using asdf

asdf is a universal version manager that handles Go, Node, Python, Ruby, and many more.

# Install the Go plugin
asdf plugin add golang https://github.com/asdf-community/asdf-golang.git

# Install specific versions
asdf install golang 1.21.13
asdf install golang 1.22.5
asdf install golang 1.23.4
asdf install golang 1.24.0

# Set global default
asdf global golang 1.22.5

# Set per-project version (creates .tool-versions file)
cd my-project
asdf local golang 1.21.13

# Verify
go version

Go Version Compatibility Table

Go Version Release Date Notable Features Minimum go.mod directive
Go 1.20 Feb 2023 Profile-guided optimization (PGO) preview, errors.Join go 1.20
Go 1.21 Aug 2023 slices, maps, cmp stdlib packages; toolchain directive in go.mod go 1.21
Go 1.22 Feb 2024 Loop variable semantics fix, math/rand/v2 go 1.22
Go 1.23 Aug 2024 Range over functions, timer changes go 1.23
Go 1.24 Feb 2025 Generic type aliases, weak pointers, benchmark improvements go 1.24

Compatibility rule: A Go installation can build modules whose go.mod specifies any version equal to or older than the installed toolchain. A module with go 1.22 in go.mod requires at minimum Go 1.22 to build.

Starting with Go 1.21, the toolchain directive in go.mod can pin the exact compiler version:

module github.com/example/myapp

go 1.22

toolchain go1.22.5

If your local Go is older than the toolchain directive, the Go toolchain will automatically download the required version (if GOTOOLCHAIN=auto, which is the default since Go 1.21).

Solution 5: IDE-Specific Fixes

VS Code

  1. Open Settings (Cmd/Ctrl + ,)
  2. Search for go.goroot
  3. Set it to match your terminal's GOROOT:
{
    "go.goroot": "/usr/local/go"
}

Or let VS Code auto-detect by clearing the value:

{
    "go.goroot": null
}
  1. Reload the VS Code window (Cmd/Ctrl + Shift + P → "Developer: Reload Window")

GoLand / IntelliJ IDEA

  1. Go to Preferences → Go → GOROOT
  2. Select the correct Go SDK from the list, or click + to add one
  3. Verify it matches your terminal Go installation

Troubleshooting Checklist

Run through this list if you are still seeing errors after the steps above:

  • [ ] which go — is it the Go installation you expect?
  • [ ] go version — correct version number?
  • [ ] go env GOROOT — points to the right directory?
  • [ ] echo $PATH — Go bin directory appears before any conflicting entries?
  • [ ] Check for a .go-version file in the project (goenv) or .tool-versions (asdf)
  • [ ] Check the go directive in go.mod — is your installed Go new enough?
  • [ ] Check for a toolchain directive in go.mod — requires Go 1.21+
  • [ ] go mod tidy — run this to sync go.mod and go.sum
  • [ ] go mod vendor — run this if the project uses a vendor directory
  • [ ] Restart the terminal after any PATH or environment changes

Common Scenarios

Scenario: Updated Go via Homebrew, still seeing old version

brew upgrade go
hash -r        # Clear bash/zsh command hash cache
go version

Scenario: CI passes but local build fails

Check:

  • go directive in go.mod
  • toolchain directive in go.mod
  • Go version used in the CI Dockerfile or runner image
  • .go-version or .tool-versions file in the repository root

Scenario: Multiple Go versions needed for different projects

Use goenv or asdf and set per-project versions:

# With goenv
cd project-a && goenv local 1.21.13
cd project-b && goenv local 1.24.0

# With asdf
cd project-a && asdf local golang 1.21.13
cd project-b && asdf local golang 1.24.0

Scenario: go mod tidy changes nothing but build still fails

The issue may be in the build cache rather than the module graph:

go clean -cache
go clean -testcache
go build ./...

Related Guides

Conclusion

The "compile: version does not match go tool version" error and its relatives — runtime.main_main·f: function main is undeclared, go: inconsistent vendoring, and build constraints exclude all Go files — all stem from version mismatches between the Go compiler, the runtime, the module requirements, or the vendored dependencies. The fastest fix is to:

  1. Ensure only one Go installation is active (which go and go env GOROOT must agree)
  2. Run go mod tidy to synchronize go.mod with your dependencies
  3. Use goenv or asdf if you need multiple versions side by side
  4. Check the go and toolchain directives in go.mod and upgrade your Go installation if necessary
Go