Introduction

TLS handshakes fail when the client and server cannot negotiate a protocol version they both support. This often appears right after a security hardening change that disables TLS 1.0 or 1.1, but it can also happen when traffic hits the wrong port, an upstream proxy terminates SSL differently than expected, or a legacy runtime cannot speak modern TLS at all.

Symptoms

  • OpenSSL reports tlsv1 alert protocol version or wrong version number
  • Modern browsers work, but older Java, Python, or appliance clients fail
  • SSL tests succeed against one endpoint while application traffic fails through another layer
  • The issue starts after a proxy, CDN, load balancer, or web server TLS policy change

Common Causes

  • The server allows only TLS 1.2 or 1.3 while the client supports only older protocols
  • A reverse proxy or load balancer terminates TLS with stricter settings than the origin
  • The client is connecting with HTTPS to a plain HTTP port, producing a misleading version error
  • Legacy libraries or JVM settings prevent the client from negotiating a supported protocol

Step-by-Step Fix

  1. 1.Test the server endpoint with explicit TLS versions
  2. 2.Confirm which protocol versions the live endpoint actually accepts before changing configuration.
bash
openssl s_client -connect example.com:443 -servername example.com -tls1_2
openssl s_client -connect example.com:443 -servername example.com -tls1_3
  1. 1.Verify every SSL termination layer, not just the origin
  2. 2.If traffic passes through ALB, Nginx, Apache, or a CDN, the failing TLS policy may live on the edge layer rather than the application server.
nginx
ssl_protocols TLSv1.2 TLSv1.3;
  1. 1.Inspect the client runtime and its actual TLS support
  2. 2.Older clients may need an upgrade or an explicit runtime setting before they can speak TLS 1.2+ reliably.
bash
java -version
python --version
curl -V
  1. 1.Fix the mismatch deliberately instead of re-enabling weak protocols by reflex
  2. 2.When possible, upgrade the client. Only re-enable older protocols temporarily if you have a clear compatibility requirement and compensating controls.

Prevention

  • Test TLS compatibility after every proxy, CDN, or certificate configuration change
  • Keep client runtimes and libraries current enough to support TLS 1.2 or newer
  • Document where TLS terminates across the request path
  • Avoid emergency protocol downgrades without understanding which clients still depend on them