Fix it fast
Most likely: The requested tag or query is not present or selectable from the source Go is actually using.
Confirm this is your error
Match the output and confirm you are troubleshooting the same failure.
go: example.com/mod@v1.2.3: invalid version: unknown revision v1.2.3
go: module example.com/mod: no matching versions for query ">v1.5.3"Check the cause
Run focused checks to identify what is failing in this environment.
go env GOPROXY GOPRIVATE GONOPROXY
go list -m -versions <module>
go list -m -retracted <module>@latestApply the safe fix
Use the smallest safe change that addresses the confirmed cause.
# After confirming compatibility
go get <module>@<existing-version>Verify it works
Repeat the relevant checks and confirm the original error is gone.
go list -m <module>@<existing-version>
go build ./...Avoid unsafe shortcuts
Keep security and data protections in place while troubleshooting.
- Do not invent a pseudo-version before confirming the real commit and repository state.
- Do not assume an auth failure is proof that the version does not exist.
What This Error Means
Read this as a precise clue about which part of the workflow broke first. Once you know the failing layer, the fix path gets much shorter.
How to Fix It
The fastest fixes here come from checking the immediate failing layer before you change anything unrelated. Make one correction at a time and re-test from the same environment.
Missing concrete revision:select an existing immutable tag or commit and correct the dependency declaration.
Query mismatch:choose an available version that meets the compatibility requirement.
Retracted release:move to a supported unretracted version after reading the retraction rationale.
Private module:repair repository or proxy access first, then repeat the version lookup.
Stale private proxy:repair its version metadata instead of bypassing it silently.
Why It Happens
There are usually a few repeatable root causes behind this message. Narrowing them down early prevents a lot of trial-and-error.
The requested tag, branch, or commit was mistyped, deleted, force-moved, or never pushed.
A semver-looking branch such as v2 is interpreted as a version-prefix query rather than an ordinary branch name.
Matching versions are retracted, excluded, or incompatible with the module path’s major version.
A private-repository authentication problem prevents Go from seeing the revision.
The configured proxy has stale or incomplete list/latest metadata.
Verify the Fix
Run go list -m <module>@<version-or-query> and confirm it returns one concrete canonical version.
Repeat the original command and review any module-file diff.
Separate a missing revision from an empty version query
Run go env GOPROXY GOPRIVATE GONOPROXY to identify the version source.
Run go list -m -versions <module> and compare the returned tags with the exact query from the error.
Run go list -m -retracted <module>@latest. For an exact revision, inspect tags and commits in the authoritative repository.
How Go resolves revisions and version queries
A tag, branch, or commit is a revision query. Go asks the proxy or VCS to resolve it and may create a pseudo-version for a commit. Queries such as latest, upgrade, patch, v1, or a range select from available versions. Retractions, exclusions, and major-version path rules can eliminate every match.
Prevent It From Coming Back
To prevent this, publish immutable semantic-version tags and avoid ambiguous semver-looking branch names in installation instructions, monitor proxy list and latest endpoints, and pin CI and tool installation to reviewed versions instead of relying on an unbounded latest query.
Docs and source code
Go module query source
Current source for version-query and package-not-in-module diagnostics. - Source
Version queries select allowed versions and package queries confirm the selected module contains the requested package.Go module query tests
Current exact examples for unknown revision and no matching versions for query. - Source
The tests distinguish a missing concrete revision from a version range with no matching release.Go Modules Reference
Official reference for module files, version selection, proxies, private modules, checksums, workspaces, and vendoring. - Source
The go command uses module paths and versions to resolve, download, and authenticate dependencies.