client-side RPC versions is not compatible with this…

Error message

client-side RPC versions is not compatible with this server, local versions: %v, peer versions: %v

What it means

Returned during an ALTS server handshake (alts.ServerHandshake) after the handshake completes, when checkRPCVersions reports the local RPC protocol version range [2.1, 2.1] does not overlap with the connecting client's reported RPC versions. This is the server-side mirror of error 183.

Solutions

Ensure all clients and the server run grpc-go versions whose advertised ALTS RPC versions overlap with [2.1, 2.1].
Complete the rolling upgrade so both ends are on the same grpc-go release.
Check the PeerRPCVersions in server logs to identify the offending client version and update it.

Example fix

// before: mixed fleet — server v1.70, some clients on a build advertising 1.0 RPC versions
creds := alts.NewServerCreds(alts.DefaultServerOptions())
s := grpc.NewServer(grpc.Creds(creds)) // some clients fail with version mismatch

// after: upgrade all clients to a grpc-go release advertising 2.1
// (no code change on server; coordinate a fleet-wide grpc-go bump)

Defensive patterns

Strategy: try-catch

Try / catch

// In the server's accept loop, log and continue rather than crashing the server.
// The error is per-connection; gRPC server already handles it, but monitor it:
go func() {
    for err := range serverErrCh {
        if strings.Contains(err.Error(), "RPC versions is not compatible") {
            metrics.ALTSVersionMismatches.Inc()
            log.Printf("client ALTS version mismatch: %v", err)
        }
    }
}()

Prevention

Keep the entire fleet on a single grpc-go version until a coordinated upgrade.
Expose ALTS version-mismatch metrics to detect clients on old builds.
Log PeerRPCVersions when available to identify the offending client version.

When it happens

Trigger: A gRPC-Go ALTS server (NewServerCreds) accepts a connection, the ALTS handshake with the metadata-server handshaker service completes, but the client's negotiated max/min RPC versions do not intersect [2.1, 2.1]. Reached only on GCP.

Common situations: Clients connecting from a newer/older grpc-go or a non-Go gRPC implementation whose ALTS RPC versions differ; mixed-version fleets during a rolling upgrade; a custom ALTS handshaker returning unexpected versions.

Related errors

AI-assisted analysis of grpc/grpc-go@0c51461d27 (2026-08-11). Data as JSON: /api/errors/f0d07f74389525a0. Report an issue: GitHub.

Appendix: source

Thrown at credentials/alts/alts.go:252

		MinRpcVersion: minRPCVersion,
	}
	shs, err := handshaker.NewServerHandshaker(ctx, hsConn, rawConn, opts)
	if err != nil {
		return nil, nil, err
	}
	secConn, authInfo, err := shs.ServerHandshake(ctx)
	if err != nil {
		return nil, nil, err
	}
	// Close the handshaker since we have obtained a connection.
	defer shs.Close()
	altsAuthInfo, ok := authInfo.(AuthInfo)
	if !ok {
		return nil, nil, errors.New("server-side auth info is not of type alts.AuthInfo")
	}
	match, _ := checkRPCVersions(opts.RPCVersions, altsAuthInfo.PeerRPCVersions())
	if !match {
		return nil, nil, fmt.Errorf("client-side RPC versions is not compatible with this server, local versions: %v, peer versions: %v", opts.RPCVersions, altsAuthInfo.PeerRPCVersions())
	}
	return secConn, authInfo, nil
}

func (g *altsTC) Info() credentials.ProtocolInfo {
	return *g.info
}

func (g *altsTC) Clone() credentials.TransportCredentials {
	info := *g.info
	var accounts []string
	if g.accounts != nil {
		accounts = make([]string, len(g.accounts))
		copy(accounts, g.accounts)
	}
	return &altsTC{
		info:      &info,
		side:      g.side,

View on GitHub (pinned to 0c51461d27)