client-side RPC versions is not compatible with this server,

Error message

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

What it means

Symmetric to the client side: in the ALTS server handshake (alts.go:250-252), after the handshake completes the server checks RPC protocol versions against the connecting client's. If the version windows don't overlap, the connection is rejected. Reported server-side.

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 03255a9237)

Solutions

Upgrade or downgrade the client to a gRPC version whose ALTS versions overlap the server's.
If both sides can move, align to a single supported gRPC release.
Avoid ALTS for cross-version or non-GCP traffic; use TLS.

Example fix

// before (server pinned to old gRPC, new client connects)
// after
# rebuild server and client from the same gRPC release
# or serve TLS:
creds, _ := credentials.NewServerTLSFromFile(cert, key)

Defensive patterns

Strategy: try-catch

Try / catch

secConn, _, err := creds.ServerHandshake(rawConn)
if err != nil {
    if strings.Contains(err.Error(), "RPC versions") {
        log.Printf("rejecting ALTS client due to version mismatch")
    }
    return err
}

Prevention

Keep the ALTS server on a gRPC version compatible with your client fleet.
Roll upgrades in an order that keeps version windows overlapping.
Log peer RPC versions on handshake failure for diagnostics.

When it happens

Trigger: An ALTS server (running on GCP) receives a client whose RPC protocol versions are incompatible — e.g. a much older or much newer client than the server's compiled ALTS range.

Common situations: Version skew between client and server gRPC builds; a client from outside the supported ALTS generation; mixed environments after a protocol bump.

Related errors

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