# SSL_do_handshake() failed (SSL: error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure) while SSL handshaking to upstream

- **ID:** `nginx/ssl-handshake-failed-client-hello`
- **Domain:** nginx
- **Category:** auth_error
- **Verification:** ai_generated
- **Fix Rate:** 82%

## Root Cause

TLS handshake failure between nginx and upstream, often due to cipher mismatch, protocol version incompatibility, or certificate validation errors.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| nginx 1.20.0 | active | — | — |
| nginx 1.22.1 | active | — | — |
| nginx 1.25.0 | active | — | — |

## Workarounds

1. **Ensure upstream server supports TLS 1.2 or higher. In nginx, set:
proxy_ssl_protocols TLSv1.2 TLSv1.3;
proxy_ssl_ciphers HIGH:!aNULL:!MD5;
This restricts protocols and ciphers to modern versions.** (80% success)
   ```
   Ensure upstream server supports TLS 1.2 or higher. In nginx, set:
proxy_ssl_protocols TLSv1.2 TLSv1.3;
proxy_ssl_ciphers HIGH:!aNULL:!MD5;
This restricts protocols and ciphers to modern versions.
   ```
2. **Check upstream certificate chain: run 'openssl s_client -connect upstream_host:443 -showcerts' to verify certificate validity and intermediate CA completeness.** (85% success)
   ```
   Check upstream certificate chain: run 'openssl s_client -connect upstream_host:443 -showcerts' to verify certificate validity and intermediate CA completeness.
   ```
3. **If upstream uses a self-signed certificate, add its CA to nginx's trust store and set:
proxy_ssl_verify on;
proxy_ssl_trusted_certificate /path/to/ca.crt;** (75% success)
   ```
   If upstream uses a self-signed certificate, add its CA to nginx's trust store and set:
proxy_ssl_verify on;
proxy_ssl_trusted_certificate /path/to/ca.crt;
   ```

## Dead Ends

- **** — Setting 'proxy_ssl_verify off;' bypasses verification but does not fix the underlying TLS incompatibility; handshake may still fail. (55% fail)
- **** — The issue is usually on the upstream server side; upgrading nginx alone does not fix upstream TLS configuration. (70% fail)
- **** — Restarting does not change TLS settings; if the handshake fails due to cipher mismatch, restarting is ineffective. (85% fail)