Fix it fast
Most likely: The version is absent from this proxy, the path is wrong, or a private module was routed to the wrong source.
Confirm this is your error
Match the output and confirm you are troubleshooting the same failure.
go: example.com/team/lib@v1.2.3: reading https://packages.example.com/go/example.com/team/lib/@v/v1.2.3.info: 404 Not Found
go: example.com/team/lib@v1.2.3: reading https://packages.example.com/go/example.com/team/lib/@v/v1.2.3.mod: 410 GoneCheck the cause
Run focused checks to identify what is failing in this environment.
go env GOPROXY GOPRIVATE GONOPROXY
go list -m <module>@<version>
go mod download -x <module>@<version>Apply the safe fix
Use the smallest safe change that addresses the confirmed cause.
# After confirming compatibility, select a version present in the intended proxy
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 mod download -x <module>@<existing-version>Avoid unsafe shortcuts
Keep security and data protections in place while troubleshooting.
- Do not treat 404/410 as equivalent to 401/403 or a proxy outage.
- Do not change fallback separators without understanding which policy failures could be bypassed.
What Go Could Not Find
The request was valid enough to perform a lookup, but the upstream source could not match it to a real package, image, version, or artifact for this environment.
Confirm the module, version, proxy, and separator
Run go env GOPROXY GOPRIVATE GONOPROXY and check the separators.
Run go list -m <module>@<version> and confirm the exact module path and canonical version requested.
Use go mod download -x <module>@<version> to identify which module endpoint and proxy returned 404 or 410.
Check the upstream tag and RepoFlow metadata before changing fallback.
Confirm the exact module or package you asked for
Before you retry, confirm the exact name, version or tag, namespace, and index or registry this environment is supposed to use. Most fixes here are about pointing at the right thing.
Missing version:publish or select an existing immutable version.
Wrong path:correct the module path and semantic major-version suffix.
Private path leak:align GOPRIVATE, GONOPROXY, and GOPROXY with the intended private-module strategy.
RepoFlow issue:correct the upstream URL or repair only the verified bad metadata entry.
Fallback policy:change comma or pipe separators only as an explicit availability and security decision.
Why It Was Not Found
Most of the time this comes down to a typo, a wrong mirror or registry, a missing platform build, or a version that exists somewhere else but not in the source this environment is querying.
The version was never tagged or has not reached the proxy.
The module path or major-version suffix is wrong.
A private module was sent to a public proxy because privacy patterns did not match.
RepoFlow points at the wrong upstream or has incomplete metadata.
Fallback occurred but every later proxy or direct origin also lacked the requested module.
Prove the Source Resolves Correctly Now
Run go list -m <module>@<version> and expect one concrete module version.
Repeat the download with -x and confirm the intended proxy or fallback serves it.
How 404 and 410 control GOPROXY fallback
A module proxy serves list, .info, .mod, and .zip endpoints. With comma-separated GOPROXY, HTTP 404 or 410 means Go may try the next entry. Other errors stop comma fallback. Pipes allow fallback after any error.
Avoid Version and Source Drift
To prevent this, validate new internal versions through RepoFlow before dependent builds use them, monitor proxy 404/410 separately from authentication and service errors, and test private path patterns before they can expose internal names to public services.
Docs and source code
Go module proxy selection source
Current implementation of GOPROXY order, comma fallback, pipe fallback, and 404/410 handling. - Source
Pipe entries fall back on any error. Comma entries fall back only when the response is not found.Managing Dependencies
Official task guidance for dependency changes and GOPROXY comma-versus-pipe fallback behavior. - Source
Comma-separated proxies fall through on 404 or 410. Pipe-separated proxies fall through on any error.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.