teamai-test/.teamai/skills/common/golang-dependency-management/references/conflicts.md

Dependency Conflicts & Resolution

Diagnosing Conflicts

# See why a module is in your build
go mod why -m github.com/some/module

# See which version is selected
go list -m github.com/some/module

# See the full requirement graph
go mod graph

# List all modules in the build
go list -m all

Resolution Strategies

Force a specific version (when two deps require incompatible versions):

go mod edit -replace=example.com/pkg@v1.2.0=example.com/pkg@v1.3.1

// go.mod
replace example.com/pkg v1.2.0 => example.com/pkg v1.3.1

Use a local fork (for debugging or patching):

replace example.com/pkg => ../my-local-fork

Block a problematic version:

go mod edit -exclude=example.com/pkg@v1.3.0

When a version is excluded, any requirement on that version is redirected to the next higher available version.

Force upgrade a transitive dependency:

go get github.com/transitive/dep@v1.5.0

This adds an explicit requirement in your go.mod, overriding whatever the transitive dependency chain would select via MVS.

Resolution Workflow

1. Run go mod graph and go mod why -m <module> to understand the dependency chain
2. Identify which of your direct dependencies pulls in the conflicting version
3. Try upgrading the direct dependency first: go get github.com/direct/dep@latest
4. If that doesn't resolve it, use replace or exclude as a temporary fix
5. Run go mod tidy to clean up
6. Verify with go build ./... and go test ./...

Important: replace and exclude directives only take effect in the main module's go.mod. They are ignored when your module is used as a dependency. Remove replace directives before publishing a library.

Retract (For Module Authors)

Mark versions as broken or accidentally published:

// go.mod
retract v1.0.0         // Contains critical bug in auth
retract [v1.1.0, v1.2.0] // Range of broken versions

Retracted versions are still downloadable but go get will not select them by default, and go list -m -u warns about them.