How to fix Error: tlsv1 alert handshake failure (TLS negotiation failed) in Node.js

What this error means

This error indicates that the TLS (Transport Layer Security) handshake between your Node.js client and the server has failed at a critical negotiation stage. During a TLS handshake, the client and server must mutually agree on encryption parameters including: - TLS protocol version (TLSv1.0, TLSv1.2, TLSv1.3, etc.) - Cipher suites for encryption and authentication - Certificate validity and chain verification - Elliptic Curve Diffie-Hellman (ECDH) parameters When these parameters cannot be agreed upon, the server sends an alert message indicating "handshake failure" and terminates the connection. This is a cryptographic negotiation failure, distinct from certificate validation errors.

Typical symptoms

• HTTPS requests fail with "tlsv1 alert handshake failure" or "alert handshake failure" message
• WebSocket connections over TLS fail to establish
• npm install fails when connecting to private registries over HTTPS
• API calls to certain endpoints fail while others succeed
• Connection timeout or immediate disconnection without establishing SSL/TLS
• Error occurs after successful connections in older Node.js versions
• Certain servers are unreachable while the same request works with curl or other tools

Common causes

1. TLS protocol version mismatch (e.g., client requires TLSv1.3 but server only supports TLSv1.2)
2. No overlapping cipher suites between client and server
3. ECDH curve negotiation failure due to unsupported curves
4. Node.js version upgrade changed default cipher suites
5. Server configured with legacy or insecure ciphers no longer supported by Node.js
6. OpenSSL security level too restrictive for server's cipher configuration
7. Incompatible elliptic curve selection between client and server
8. Missing or incompatible Certificate Authority certificates for verification

How to fix "Error: tlsv1 alert handshake failure (TLS negotiation failed)"

# Test the connection with openssl
openssl s_client -connect example.com:443 -showcerts

# Look at the output:
# - "Verify return code: 0 (ok)" = TLS successful, issue is elsewhere
# - "alert handshake failure" = TLS negotiation failed (this error)
# - "Verify return code: 20" = Certificate validation failed (different error)

# Test TLSv1.3
openssl s_client -connect example.com:443 -tls1_3 -showcerts 2>&1 | grep -E 'Protocol|Ciphers'

# Test TLSv1.2
openssl s_client -connect example.com:443 -tls1_2 -showcerts 2>&1 | grep -E 'Protocol|Ciphers'

# Test TLSv1.0 (if needed)
openssl s_client -connect example.com:443 -tls1 -showcerts 2>&1 | grep -E 'Protocol|Ciphers'

# Check your current version
node --version

# Update using nvm (recommended)
nvm install --lts
nvm use --lts

# Or install from nodejs.org

const https = require('https');

const options = {
  hostname: 'example.com',
  port: 443,
  path: '/api',
  method: 'GET',
  minVersion: 'TLSv1.2',  // Require at least TLS 1.2
  maxVersion: 'TLSv1.3',  // Allow up to TLS 1.3
  ciphers: 'HIGH:!aNULL:!MD5'  // OpenSSL cipher string
};

https.request(options, (res) => {
  console.log('Connected successfully');
}).on('error', (err) => {
  console.error('TLS error:', err.message);
}).end();

const axios = require('axios');
const https = require('https');

const agent = new https.Agent({
  minVersion: 'TLSv1.2',
  ciphers: 'HIGH:!aNULL:!MD5'
});

axios.get('https://example.com/api', { httpsAgent: agent });

# For testing purposes only - NOT for production
node --tls-min-v1.0 your-app.js

# List curves supported by Node.js
node -e "console.log(require('crypto').getCurves())"

# Test OpenSSL available curves
openssl ecparam -list_curves

const tls = require('tls');
const https = require('https');

const options = {
  hostname: 'example.com',
  port: 443,
  ecdhCurve: 'auto'  // Let Node.js select
};

https.request(options, (res) => {
  // Handle response
}).end();

# Run with TLS debugging enabled
NODE_DEBUG=tls node your-app.js 2>&1 | head -50

# Or with more verbose output
NODE_DEBUG=tls,crypto node your-app.js 2>&1 | head -100

Advanced notes

# Check OpenSSL version and available ciphers
openssl version
openssl ciphers 'ALL'

OPENSSL_CONF=/dev/stdin node -e "..." << 'EOF'
[default]
openssl_conf = openssl_init

[openssl_init]
ssl_conf = ssl_sect

[ssl_sect]
system_default = system_default_sect

[system_default_sect]
MinProtocol = TLSv1.0
CipherString = DEFAULT@SECLEVEL=1
EOF

const options = {
  minVersion: 'TLSv1.0',  // Explicitly allow older versions
};

# Alpine: May have older OpenSSL
FROM node:18-alpine
RUN apk add --update openssl

# Or use Debian-based for more recent OpenSSL
FROM node:18-bullseye

Frequently asked questions

What does "ERR_TLS_HANDSHAKE_FAILURE" mean?

js client and the server has failed at a critical negotiation stage. ) - Cipher suites for encryption and authentication - Certificate validity and chain verification - Elliptic Curve Diffie-Hellman (ECDH) parameters When these parameters cannot be agreed upon, the server sends an alert message indicating "handshake failure" and terminates the connection. This is a cryptographic negotiation failure, distinct from certificate validation errors.

How do I fix "ERR_TLS_HANDSHAKE_FAILURE"?

This error occurs when Node.js fails to complete a TLS handshake during an HTTPS or secure WebSocket connection. The client and server cannot agree on compatible encryption protocols, cipher suites, or certificate parameters, causing the secure connection to be rejected.

What causes "ERR_TLS_HANDSHAKE_FAILURE"?

TLS protocol version mismatch (e.g., client requires TLSv1.3 but server only supports TLSv1.2) No overlapping cipher suites between client and server ECDH curve negotiation failure due to unsupported curves

Is the "ERR_TLS_HANDSHAKE_FAILURE" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• Error: tlsv1 alert unknown ca (untrusted certificate authority)

  TLS alert: unknown CA (untrusted certificate authority)

  HIGH

• Error: tlsv1 alert bad certificate (peer rejected certificate)

  TLS alert: bad certificate (peer rejected certificate)

  HIGH

• Error: TLS handshake timeout (connection timeout during TLS negotiation)

  TLS handshake timeout in Node.js

  HIGH

• Error: Invalid timezone string (TZ environment variable malformed)

  Invalid timezone string from TZ environment variable

  MEDIUM

• Error: zlib error Z_DATA_ERROR (corrupted compressed data)

  Z_DATA_ERROR: Corrupted compressed data

  MEDIUM

• Error: Could not find package.json in current directory (npm module resolution)

  How to fix "Could not find package.json in current directory" in Node.js

  MEDIUM

Official resources & further reading

• 📚Node.js Official Documentation
• 📖
  Node.js TLS (SSL) Documentation(Official Docs)
• 🐙
  tls.connect() fails with SSLv3 alert handshake failure(GitHub)
• 🐙
  SSL routines sslv3 alert handshake failure troubleshooting(GitHub)
• 📖
  Apigee Edge: TLS/SSL Handshake Failures Guide(Official Docs)