TLS handshake failed on grpc.subglow.io

Root causes

Ranked by frequency. First cause is the one to check first.

1. 01Alpine-based Docker image missing `ca-certificates` package.
2. 02Out-of-date OS root store (Ubuntu 18.04 or older).
3. 03Corporate proxy (Zscaler, Palo Alto) intercepting TLS and presenting its own cert — common on dev laptops, never on server deploys.
4. 04Client sending ALPN `h2` but an intermediate LB is terminating with ALPN `http/1.1` — causes TLS to succeed then gRPC to immediately fail.
5. 05SNI not set — very rare, but some custom gRPC clients forget to send SNI and the provider serves the wrong certificate.

Fix steps

1. 1

   Install ca-certificates in Docker

   Add `RUN apk add --no-cache ca-certificates` to Alpine-based Dockerfiles, or `RUN apt-get install -y ca-certificates && update-ca-certificates` on Debian.

2. 2

   Test with curl first

   `curl -v https://grpc.subglow.io:443`. If curl fails TLS handshake on the same machine, fix the OS cert store. If curl succeeds but your Go/Rust binary fails, it's a language-specific root bundle issue.

3. 3

   Disable custom TLS verification in dev only

   Never disable cert verification in production. In dev, for fast diagnosis, Rust's tonic accepts `ClientTlsConfig::new().insecure(true)` — if that works, you've confirmed it's a CA issue, not a protocol mismatch.

Related errors

• UNAVAILABLE: connection refused
  Your gRPC client got `Status { code: Unavailable }` with `connection refused` (or `transport is closing`). The TCP handshake never completed — either you're hitting the wrong port, TLS is misconfigured, or the endpoint is genuinely down.
• UNAUTHENTICATED — missing x-api-key
  `Status { code: Unauthenticated }` on a Yellowstone gRPC subscribe means the server didn't see a valid API key in the metadata. The single most common cause is attaching the key to the client's constructor but not to the individual streaming call.