golang/go · error

can't request explicit version of "tool" pattern

Error message

can't request explicit version of "tool" pattern

What it means

Returned by query.validate when the pattern resolves to the 'tool' meta-package (the set of Go toolchain binaries) AND the user supplied an explicit @version suffix. Meta-packages are resolved by the local toolchain and cannot be pinned to a module version. Triggered only when q.pattern != q.raw (i.e. raw input was something like 'tool@x' that collapsed to 'tool').

Source

Thrown at src/cmd/go/internal/modget/query.go:207

		// If there is no main module, "all" is not meaningful.
		if !ld.HasModRoot() {
			return fmt.Errorf(`cannot match "all": %v`, modload.NewNoMainModulesError(ld))
		}
		if !versionOkForMainModule(q.version) {
			// TODO(bcmills): "all@none" seems like a totally reasonable way to
			// request that we remove all module requirements, leaving only the main
			// module and standard library. Perhaps we should implement that someday.
			return &modload.QueryUpgradesAllError{
				MainModules: ld.MainModules.Versions(),
				Query:       q.version,
			}
		}
	}

	if search.IsMetaPackage(q.pattern) && q.pattern != "all" {
		if q.pattern != q.raw {
			if q.pattern == "tool" {
				return fmt.Errorf("can't request explicit version of \"tool\" pattern")
			}
			return fmt.Errorf("can't request explicit version of standard-library pattern %q", q.pattern)
		}
	}

	return nil
}

// String returns the original argument from which q was parsed.
func (q *query) String() string { return q.raw }

// ResolvedString returns a string describing m as a resolved match for q.
func (q *query) ResolvedString(m module.Version) string {
	if m.Path != q.pattern {
		if m.Version != q.version {
			return fmt.Sprintf("%v (matching %s@%s)", m, q.pattern, q.version)
		}
		return fmt.Sprintf("%v (matching %v)", m, q)

View on GitHub (pinned to b6b368adc5)

Solutions

1. Drop the version: `go get tool` is accepted but does not upgrade anything.
2. To change the Go toolchain, use `go get toolchain@<version>` (or `go get go@<version>`) instead of `go get tool@<version>`.
3. Install a specific tool binary via `go install golang.org/x/tools/<cmd>@<version>` rather than the 'tool' meta-package.

Example fix

// before
$ go get tool@1.21.0
// after
$ go get toolchain@1.21.0

// Reject explicit versions on meta-packages before calling go get.
var metaPackages = map[string]bool{"all": true, "std": true, "cmd": true, "tool": true}

func validateGetArg(arg string) error {
    pkg, ver, _ := strings.Cut(arg, "@")
    if ver != "" && metaPackages[pkg] {
        if pkg == "tool" {
            return fmt.Errorf("cannot version the %q meta-package; use `go get toolchain@%s`", pkg, ver)
        }
        return fmt.Errorf("cannot version the %q standard-library meta-package", pkg)
    }
    return nil
}

When it happens

Trigger: Running `go get tool@1.21.0`, `go get tool@latest`, or any query whose raw form has a version suffix but whose normalized pattern equals 'tool'. Reached from query.validate when search.IsMetaPackage(pattern) is true, pattern != 'all', pattern != raw, and pattern == "tool".

Common situations: Trying to upgrade the Go toolchain via `go get tool@version` instead of the supported `go get toolchain@version`; confusing the 'tool' wildcard meta-package with the 'toolchain' module.

Related errors

• ${GoModToolVersion} is required for tool directives in go.mo
• %s%s is not within module%s rooted at %s
• no package to get in current directory
• %s%s is not a package in module rooted at %s
• %v matches packages in %v but not %v: specify a different ve

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/b8622b557738f520. Report an issue: GitHub.