communication network_error ai_generated true

rpc error: code = Unavailable desc = connection closed before server preface received

ID: communication/grpc-connection-reset-by-peer-tls

Also available as: JSON · Markdown · 中文
83%Fix Rate
87%Confidence
1Evidence
2024-06-15First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
gRPC Go v1.62.0 active — — —
gRPC Python v1.60.0 active — — —
gRPC Java v1.61.0 active — — —
Envoy proxy v1.29.0 active — — —
NGINX 1.25.3 active — — —

Root Cause

gRPC client fails to receive the HTTP/2 server preface (the initial SETTINGS frame) due to TLS handshake failure, proxy timeout, or server not supporting HTTP/2 over the negotiated protocol.

generic

中文

gRPC客户端因TLS握手失败、代理超时或服务器不支持协商协议上的HTTP/2而无法收到HTTP/2服务器前言（初始SETTINGS帧）。

Official Documentation

https://grpc.io/docs/guides/error/

Workarounds

  1. 85% success Verify TLS configuration on the server: ensure the server supports HTTP/2 (requires ALPN with h2). For NGINX, add 'http2 on;' and 'ssl_protocols TLSv1.2 TLSv1.3;' to the server block. 
    Verify TLS configuration on the server: ensure the server supports HTTP/2 (requires ALPN with h2). For NGINX, add 'http2 on;' and 'ssl_protocols TLSv1.2 TLSv1.3;' to the server block.
  2. 80% success Check if a proxy (e.g., Envoy, NGINX) is stripping the ALPN header or not forwarding HTTP/2; configure the proxy to pass through HTTP/2: for Envoy, set 'typed_config: "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager"' with 'codec_type: AUTO'. 
    Check if a proxy (e.g., Envoy, NGINX) is stripping the ALPN header or not forwarding HTTP/2; configure the proxy to pass through HTTP/2: for Envoy, set 'typed_config: "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager"' with 'codec_type: AUTO'.

中文步骤

  1. Verify TLS configuration on the server: ensure the server supports HTTP/2 (requires ALPN with h2). For NGINX, add 'http2 on;' and 'ssl_protocols TLSv1.2 TLSv1.3;' to the server block.
  2. Check if a proxy (e.g., Envoy, NGINX) is stripping the ALPN header or not forwarding HTTP/2; configure the proxy to pass through HTTP/2: for Envoy, set 'typed_config: "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager"' with 'codec_type: AUTO'.

Dead Ends

Common approaches that don't work:

  1. Disable TLS entirely and use plaintext gRPC 80% fail

    Disabling TLS exposes data to eavesdropping and violates security policies; the error may persist if the root cause is proxy timeout, not TLS.

  2. Increase the gRPC client timeout to a very high value (e.g., 5 minutes) 85% fail

    A high timeout does not fix the underlying issue—if the server never sends the preface, the connection will still be closed after a long delay.

  3. Use HTTP/1.1 instead of HTTP/2 in the proxy configuration 95% fail

    gRPC requires HTTP/2; downgrading to HTTP/1.1 breaks gRPC streaming and causes different errors like 'Unimplemented'.