Resolving Compatibility Issues Between etcd v3.3/v3.4, gRPC, and Protobuf

In recent years many developers have encountered incompatibility problems when combining the micro‑service stack grpc + grpc-gateway + etcd + protobuf + protoc-gen-go . The components are maintained by different teams, leading to version mismatches that can block development.

Various Compatibility Issues

When etcd is at version 3.3 or 3.4 and gRPC is newer than v1.27, three typical errors appear:

1. Missing grpc/naming

The package google.golang.org/grpc/naming is no longer shipped because the etcd client imports an experimental package from grpc‑go. Running go mod tidy yields the following error:

go: finding module for package google.golang.org/grpc/naming
go: finding module for package google.golang.org/grpc/examples/helloworld/helloworld
go: found google.golang.org/grpc/examples/helloworld/helloworld v0.0.0-20231026203026-8cb98464e599
...
go: google.golang.org/grpc/naming: module google.golang.org/grpc@latest found (v1.59.0), but does not contain package google.golang.org/grpc/naming

The grpc‑go maintainers state that this package is experimental and may be removed at any time.

2. Missing etcd/clientv3/balancer/picker

Because the experimental package was removed, etcd v3.3 compilation fails with undefined symbols such as balancer.PickOptions and resolver.BuildOption :

$ go get go.etcd.io/etcd/clientv3
# github.com/coreos/etcd/clientv3/balancer/resolver/endpoint
...: undefined: resolver.BuildOption
...: undefined: resolver.ResolveNowOption
...: undefined: balancer.PickOptions

The author filed an issue and a PR to etcd, but the fix was only merged in later releases.

3. Missing grpc.SupportPackageIsVersion6

When protoc-gen-go and gRPC versions are mismatched, the compiler reports:

Getting error undefined: grpc.SupportPackageIsVersion6 and undefined: grpc.ClientConnInterface

Upgrading gRPC to ≥ 1.27 solves the problem, but the etcd SDK still pins the older gRPC version, creating a dead‑lock.

Underlying Reason

All three issues trace back to etcd v3.3’s lack of proper Go module support. The old releases do not provide a go.mod file, and even v3.4’s module is broken (see etcd‑io/etcd#11154).

Solution

The community finally released etcd v3.5, which fully supports Go modules and splits the project into independent modules such as api , client , raft , server , etcdctl , and bbolt . This modularization eliminates cross‑dependency problems.

For new projects, the recommendation is to use etcd v3.5 or later and avoid the older v3.3/v3.4 releases.

Remaining Caveats

The modularization only applies to etcd v3.5+. Legacy projects that still rely on etcd v2 or older v3.x versions must either migrate their data to v3 or implement a custom lightweight SDK, as the old versions receive no further compatibility fixes.

Conclusion

The long‑standing compatibility issues between etcd, gRPC, and protobuf have been largely resolved with the introduction of etcd v3.5’s module system, but projects stuck on older versions will continue to face the same obstacles.

References

[1] etcd‑io/etcd/issues/11154: https://github.com/etcd-io/etcd/issues/11154