Fixing 'go: inconsistent vendoring' in Go Modules

Understanding the Error

The go: inconsistent vendoring error occurs when your go.mod file and your vendor/ directory are out of sync. When you use the -mod=vendor flag (which is often the default in modern Go versions if a vendor folder exists), the Go toolchain checks vendor/modules.txt to ensure it matches what is defined in go.mod.

If you add a new dependency to go.mod but forget to update the vendor directory, or if a git merge results in a mismatch, Go will stop the build and throw this error to prevent you from building with incorrect or missing source code.

go: inconsistent vendoring in /app:
    github.com/foo/bar@v1.2.3: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt

Step-by-Step Fix

Step 1: Synchronize your dependencies

The most common cause is simply forgetting to run the vendor command after adding a new package. Run the following commands in your project root:

# Clean up unused dependencies and add missing ones to go.mod
go mod tidy

# Update the vendor directory to match go.mod
go mod vendor

The go mod vendor command rewrites the vendor/ folder and regenerates vendor/modules.txt, which should resolve the inconsistency.

Step 2: Check for Git Merge Conflicts

If you recently merged a branch, it is possible that go.mod was updated but vendor/modules.txt was not, or vice versa. If go mod vendor doesn't immediately fix it, try deleting the vendor folder entirely and recreating it:

rm -rf vendor/
go mod tidy
go mod vendor

Step 3: Fix Inconsistencies in Docker

If this error happens inside a Docker container but not on your local machine, check your Dockerfile. Often, developers copy go.mod and go.sum but forget to copy the vendor folder, or they run go build assuming the container will download dependencies while the environment is set to use the vendor directory.

Ensure your Dockerfile includes the vendor directory if you intend to use it:

# Example Dockerfile snippet
COPY go.mod go.sum ./
COPY vendor/ vendor/
RUN go build -mod=vendor -o myapp

Alternatively, if you don't want to use the vendor folder in Docker, ensure the vendor directory is ignored via .dockerignore and do not use the -mod=vendor flag.

Step 4: Verify the Go Version

Sometimes, different Go versions handle vendoring differently. Ensure that the version of Go used to run go mod vendor matches the version used to build the application. You can check your version with:

go version

Verification: How to confirm the fix worked

To verify that the inconsistency is gone, run a build command explicitly forcing the use of the vendor directory:

go build -mod=vendor ./...

If the command completes without output, the vendor/modules.txt file is now correctly synced with go.mod. You should also see that vendor/modules.txt now contains the missing package mentioned in the error message.

Pro-Tips for Avoiding This Error

• CI/CD Checks: Add a step in your CI pipeline that runs go mod tidy and go mod vendor, then checks if git status --porcelain is empty. This ensures no one forgets to commit the updated vendor folder.
• Go Environment: If you don't actually need a vendor folder, delete it. Go modules work perfectly fine by downloading dependencies to the module cache ($GOPATH/pkg/mod) without a local vendor directory.
• Read-Only Flag: In build environments, use go build -mod=readonly to ensure the build fails if go.mod needs updates, rather than letting it change files silently.