server-side RPC versions are not compatible with this…

Error message

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

What it means

Returned during an ALTS client handshake (alts.ClientHandshake) after the handshake completes successfully, when checkRPCVersions reports that the locally advertised RPC protocol version range does not overlap with the peer (server) reported range. The local range is hardcoded to [2.1, 2.1]. A mismatch means the two ALTS endpoints cannot agree on a common gRPC RPC protocol version.

Solutions

Align the gRPC version on the client and server so both advertise compatible ALTS RPC protocol versions (currently 2.1).
Upgrade (or downgrade) the grpc-go dependency on both ends to a matching release tag.
If you control both endpoints, verify the RpcProtocolVersions returned by the handshaker service and file an issue if they diverge unexpectedly.

Example fix

// before: client on grpc-go v1.70, server on a build advertising RPC version 3.0
creds := alts.NewClientCreds(alts.DefaultClientOptions())
conn, _ := grpc.Dial(addr, grpc.WithTransportCredentials(creds)) // version mismatch error

// after: pin both client and server to the same grpc-go release
go get google.golang.org/grpc@v1.70.0 // on both sides

Defensive patterns

Strategy: try-catch

Try / catch

// Wrap the dial and surface version-mismatch as a typed error the app can handle.
func dialAlTS(addr string, creds credentials.TransportCredentials) (*grpc.ClientConn, error) {
    conn, err := grpc.Dial(addr, grpc.WithTransportCredentials(creds))
    if err != nil {
        if strings.Contains(err.Error(), "RPC versions are not compatible") {
            return nil, fmt.Errorf("ALTS version mismatch with %s: upgrade grpc-go on both ends: %w", addr, err)
        }
        return nil, err
    }
    return conn, nil
}

Prevention

Pin the same grpc-go version on ALTS clients and servers.
During rolling upgrades, verify ALTS RPC version ranges overlap before shifting traffic.
Log the full error (including local/peer versions) to quickly identify the mismatched side.

When it happens

Trigger: A gRPC-Go ALTS client (NewClientCreds) completes the ALTS cryptographic handshake to an ALTS server, but the server's negotiated max/min RPC versions fall entirely outside [2.1, 2.1]. This path is reached only on GCP (vmOnGCP==true), after the handshaker service returns a result with PeerRPCVersions.

Common situations: Connecting from a much newer or older grpc-go build (whose hardcoded min/max RPC versions differ from 2.1) to a server running a different gRPC version, or to a handshaker service that reports unexpected versions. Can also appear when a test/staging environment runs a pre-release or custom-built gRPC.

Related errors

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

Appendix: source

Thrown at credentials/alts/alts.go:212

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

// ServerHandshake implements the server side ALTS handshaker.
func (g *altsTC) ServerHandshake(rawConn net.Conn) (_ net.Conn, _ credentials.AuthInfo, err error) {
	if !vmOnGCP {
		return nil, nil, ErrUntrustedPlatform
	}
	// Connecting to ALTS handshaker service.
	hsConn, err := service.Dial(g.hsAddress)
	if err != nil {
		return nil, nil, err
	}
	// Do not close hsConn since it's shared with other handshakes.

	ctx, cancel := context.WithTimeout(context.Background(), defaultTimeout)
	defer cancel()

View on GitHub (pinned to 0c51461d27)