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

- **ID:** `communication/grpc-connection-reset-by-peer-tls`
- **Domain:** communication
- **Category:** network_error
- **Verification:** ai_generated
- **Fix Rate:** 83%

## 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.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| 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 | — | — |

## Workarounds

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.** (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.
   ```
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'.** (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'.
   ```

## Dead Ends

- **Disable TLS entirely and use plaintext gRPC** — Disabling TLS exposes data to eavesdropping and violates security policies; the error may persist if the root cause is proxy timeout, not TLS. (80% fail)
- **Increase the gRPC client timeout to a very high value (e.g., 5 minutes)** — 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. (85% fail)
- **Use HTTP/1.1 instead of HTTP/2 in the proxy configuration** — gRPC requires HTTP/2; downgrading to HTTP/1.1 breaks gRPC streaming and causes different errors like 'Unimplemented'. (95% fail)