go network_error ai_generated true

rpc error: code = Unavailable desc = connection error: desc = "transport: authentication handshake failed: tls: first record does not look like a TLS handshake"

ID: go/grpc-unavailable-connection-timeout

Also available as: JSON · Markdown · 中文
80%Fix Rate
87%Confidence
0Evidence
2024-07-22First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
1.0 active — — —
1.1 active — — —

Root Cause

The client is using TLS but the server expects plaintext, or vice versa, causing a handshake failure.

generic

中文

客户端使用TLS但服务器期望明文，反之亦然，导致握手失败。

Workarounds

  1. 95% success Match TLS settings between client and server: either both use TLS or both use plaintext. 
    // Server with TLS
creds, err := credentials.NewServerTLSFromFile("server.crt", "server.key")
if err != nil { log.Fatal(err) }
s := grpc.NewServer(grpc.Creds(creds))
// Client with TLS
creds, err := credentials.NewClientTLSFromFile("ca.crt", "x")
if err != nil { log.Fatal(err) }
conn, err := grpc.Dial("localhost:8080", grpc.WithTransportCredentials(creds))
  2. 90% success Use insecure connection for development (not recommended for production). 
    conn, err := grpc.Dial("localhost:8080", grpc.WithInsecure())

Dead Ends

Common approaches that don't work:

  1. Ignore TLS configuration and assume automatic negotiation. 100% fail

    gRPC does not auto-negotiate TLS; explicit configuration is required.

  2. Use a self-signed certificate without proper validation. 70% fail

    The server may reject self-signed certs if it requires a trusted CA.