Go "inconsistent vendoring" - Fix in CI

By Kaveh Alemi·Latchkey

When a vendor/ directory exists, Go builds from it and checks vendor/modules.txt against go.mod. If they disagree, the build refuses rather than guessing.

What this error means

A build fails with inconsistent vendoring and a list of modules that are in go.mod but not in vendor/modules.txt (or the reverse). It means the vendor tree was not regenerated after a go.mod change.

go: inconsistent vendoring in /home/runner/work/app:
	github.com/pkg/errors@v0.9.1: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt
	To ignore the vendor directory, use -mod=mod or -mod=readonly.
	To sync the vendor directory, run:
		go mod vendor

Diagnose it: module path, proxy, or checksum?

Go module errors name the module but rarely the layer that failed. Separate the three: the module path does not resolve, the proxy cannot serve it, or the checksum database disagrees with what was downloaded.

# what Go resolves and from where
go env GOPROXY GOSUMDB GOPRIVATE GOFLAGS

# does the module resolve at all, bypassing the build?
go list -m -versions github.com/org/module

# verify the module cache against go.sum
go mod verify

# private modules must be excluded from proxy and sumdb
go env -w GOPRIVATE=github.com/yourorg/*

Common causes

vendor tree not regenerated

go.mod changed but go mod vendor was not re-run, so vendor/modules.txt is stale relative to the requirements.

Partial vendor commit

Some vendored files or modules.txt were left out of the commit, leaving the tree internally inconsistent.

How to fix it

Regenerate and commit the vendor tree

1. Run go mod vendor to rebuild vendor/ and vendor/modules.txt from go.mod.
2. Stage the entire vendor directory plus modules.txt and commit.

go mod vendor
git add vendor go.mod go.sum
git commit -m "go mod vendor"

Keep CI in vendor mode

1. Build with -mod=vendor so CI uses the committed tree.
2. Verify the tree is current with a diff guard.

go mod vendor
git diff --exit-code vendor
go build -mod=vendor ./...

How to prevent it

• Re-run go mod vendor after any go.mod change.
• Commit the whole vendor/ tree, not a subset.
• Add a git diff --exit-code vendor guard to CI.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation