gRPC: Ssl handshake failed / authentication handshake failed SSL / TLS Origin: Network Last updated 4 Nov 2026

gRPC: rpc error: code = Unavailable desc = connection error: desc = "transport: authentication handshake failed: x509: certificate signed by unknown authority"

A gRPC client could not complete TLS to the server — untrusted certificate, name mismatch, or plaintext/TLS mismatch.

Exact message you may see transport: authentication handshake failed: x509: certificate signed by unknown authorityrpc error: code = Unavailable desc = connection error: desc = transport: authentication handshake failedSsl handshake failed grpcE0000 ssl_transport_security.cc: Handshake failed with fatal error SSL_ERROR_SSLtransport: authentication handshake failed: tls: first record does not look like a TLS handshake
Explore the map of this error Full error map →
Seen on: SSL Go

Meaning

gRPC requires you to choose TLS or insecure explicitly. Insecure client to a TLS server (or vice versa) gives handshake errors. Use the hostname in the certificate (ServerName), load the CA with credentials.NewClientTLSFromFile, and ensure ALPN h2 is supported by proxies/load balancers.

Common causes

  • Client using insecure credentials against a TLS port (or reverse)
  • Certificate not trusted by the client
  • SNI/server name mismatch
  • Load balancer without HTTP/2 (ALPN h2) support
  • Expired certificate

⚡ Quick fix

  1. Match client and server modes (TLS vs insecure)
  2. Provide the CA file or system roots
  3. Set the correct server name override when testing

Detailed fix by platform

Linux

  1. grpcurl -cacert ca.pem host:443 list or grpcurl -plaintext host:50051 list to test both modes

How to diagnose

  1. Mode — TLS or plaintext?
  2. CA — Trusted?
  3. ALPN — h2 supported?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Network. Errors that are often confused with or caused by this one (click to open):

Certificate pinning failure! — Android/OkHttp: javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure! Peer certificate chain: sha256/... Pinned certificates for api.example.com (SSL / TLS)Certificate pinning f…EOF occurred in violation of protocol — Python: ssl.SSLEOFError: EOF occurred in violation of protocol (_ssl.c:2396) (SSL / TLS)EOF occurred in viola…Received fatal alert: handshake_failure — Java: javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure (SSL / TLS)Received fatal alert:…SSL routines: wrong version number — OpenSSL: error:1408F10B:SSL routines:ssl3_get_record:wrong version number (SSL / TLS)SSL routines: wrong v…sslv3 alert handshake failure — OpenSSL: error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure (SSL alert number 40) (SSL / TLS)sslv3 alert handshake…tlsv1 unrecognized name (SNI) — OpenSSL: SSL alert number 112 — tlsv1 unrecognized name (SSL / TLS)tlsv1 unrecognized na…x509: certificate is valid for X, not Y — Go: x509: certificate is valid for www.example.com, not api.example.com (Go)x509: certificate is …x509: certificate signed by unknown authority — Go: x509: certificate signed by unknown authority (Go)x509: certificate sig…gRPC: Ssl…

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.