Fix it fast
Most likely: Dependency or replacement declarations changed without regenerating vendor metadata in the active mode.
Confirm this is your error
Match the output and confirm you are troubleshooting the same failure.
go: inconsistent vendoring in /workspace:
example.com/p@v1.0.0: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt
To sync the vendor directory, run:
go mod vendor
go: inconsistent vendoring in /workspace:
example.com/p@v1.0.0: is replaced in a/go.mod, but not marked as replaced in vendor/modules.txt
To sync the vendor directory, run:
go work vendorCheck the cause
Run focused checks to identify what is failing in this environment.
go version
go env GOWORK GOFLAGS
git diff -- go.mod go.sum go.work go.work.sum vendor/modules.txtApply the safe fix
Use the smallest safe change that addresses the confirmed cause.
# Single module
go mod vendor
# Active workspace
go work vendorVerify it works
Repeat the relevant checks and confirm the original error is gone.
git diff -- vendor
go build -mod=vendor ./...Avoid unsafe shortcuts
Keep security and data protections in place while troubleshooting.
- Do not edit
vendor/modules.txtby hand. - Do not use
-mod=modas a permanent CI bypass when the repository policy requires vendored builds.
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.
Confirm the dependency graph first. Run go mod tidy only after reviewing its preview or diff.
Single-module mode:run go mod vendor and review the full vendor diff.
Workspace mode:run go work vendor from the workspace root and review the result.
Unintended workspace:use GOWORK=off only when the repository is deliberately single-module.
Accidental drift:restore the last reviewed module and vendor files instead of regenerating from an unknown graph.
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.
A dependency changed in go.mod but the vendor directory was not regenerated.
A replace directive changed locally or in go.work without a matching vendor update.
The repository switched between single-module and workspace vendoring commands.
Developers and CI generated vendor state with different Go versions.
Someone edited vendor/modules.txt or files under vendor/ manually.
Verify the Fix
Run the appropriate vendor command again and expect no new diff, and run go build -mod=vendor ./... from the same module or workspace context that originally failed.
Compare the active graph with generated vendor metadata
Run go version and go env GOWORK GOFLAGS to identify module or workspace mode. Workspace vendoring requires Go 1.22+.
Review recent changes to go.mod, go.sum, go.work, go.work.sum, and vendor/modules.txt together.
On Go 1.23+, run go mod tidy -diff from each affected module and inspect replacements before regenerating vendor output.
How Go verifies vendor/modules.txt
Vendor mode loads dependencies from vendor/ and reads versions, explicit requirements, and replacements from vendor/modules.txt. Go compares that generated file with the active module or workspace graph and stops when they differ.
Prevent It From Coming Back
To prevent this, pin the Go version used to generate vendor state and review dependency and vendor changes together, never hand-edit vendor/modules.txt, and make the single-module versus workspace vendoring command explicit in contributor and CI scripts.
Docs and source code
Go vendoring consistency source
Current source for inconsistent vendoring and the module-versus-workspace synchronization command. - Source
Go recommends go mod vendor or go work vendor according to the active mode.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.Go 1.22 Release Notes
Official introduction of workspace vendoring and go work vendor. - Source
Go 1.22 added workspace vendor directories created by go work vendor.Go 1.14 Release Notes
Official introduction of automatic vendor mode and consistency checking. - Source
Go 1.14 automatically uses a consistent vendor directory for eligible modules.