How to fix Error: SSL_ERROR_BAD_HANDSHAKE (TLS handshake failed) in Node.js

What this error means

The SSL_ERROR_BAD_HANDSHAKE error indicates that Node.js failed to complete the TLS/SSL handshake process when establishing a secure connection. The TLS handshake is a multi-step negotiation where the client and server agree on protocol versions, cipher suites, exchange certificates, and generate encryption keys to create a secure session. When this handshake fails, it means the client and server were unable to find a mutually compatible configuration. This could be due to protocol version incompatibilities (e.g., one side only supports TLS 1.0 while the other requires TLS 1.2+), cipher suite mismatches where no common encryption algorithm exists, certificate validation failures, or network-level issues interrupting the handshake sequence. Node.js has strict security defaults that prefer modern protocols (TLS 1.2+) and strong cipher suites with perfect forward secrecy. While this improves security, it can cause handshake failures when connecting to servers with outdated configurations or when using self-signed certificates without proper configuration.

Typical symptoms

• HTTPS requests fail immediately during connection establishment
• Error message contains "SSL_ERROR_BAD_HANDSHAKE" or "TLS handshake failed"
• Connection works with curl or browsers but fails in Node.js
• Error occurs when connecting to servers with self-signed certificates
• Requests timeout during the initial SSL/TLS negotiation phase
• Works on some systems but fails on others with different Node.js versions
• Certificate verification errors appear alongside handshake failures

Common causes

1. Protocol version mismatch between client and server (e.g., server only supports TLS 1.0/1.1 while Node.js requires TLS 1.2+)
2. No mutually supported cipher suites between client and server
3. Server using self-signed certificates without proper CA configuration in Node.js
4. Missing or incomplete certificate chain on the server
5. System clock significantly different from actual time, causing certificate validity issues
6. SNI (Server Name Indication) not properly configured on the server
7. Outdated Node.js version lacking support for modern TLS protocols
8. Server using weak or deprecated ciphers (RC4, DES) that Node.js rejects by default
9. ECDH curve incompatibility between client and server
10. Firewall or proxy interfering with TLS handshake packets

How to fix "Error: SSL_ERROR_BAD_HANDSHAKE (TLS handshake failed)"

# Test TLS connection and view certificate details
openssl s_client -connect example.com:443 -servername example.com

# Check supported TLS versions
openssl s_client -connect example.com:443 -tls1_2
openssl s_client -connect example.com:443 -tls1_3

# List supported cipher suites
openssl s_client -connect example.com:443 -cipher 'ALL' -servername example.com

# Check your current Node.js version
node --version

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

# Or download from nodejs.org
# https://nodejs.org/

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

const options = {
  hostname: 'example.com',
  port: 443,
  path: '/',
  method: 'GET',
  ca: fs.readFileSync('/path/to/ca-cert.pem'),
  // Optionally specify minimum TLS version
  minVersion: 'TLSv1.2',
};

const req = https.request(options, (res) => {
  console.log('Status:', res.statusCode);
  res.on('data', (d) => process.stdout.write(d));
});

req.on('error', (error) => {
  console.error('Error:', error);
});

req.end();

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

const agent = new https.Agent({
  ca: fs.readFileSync('/path/to/ca-cert.pem'),
  minVersion: 'TLSv1.2',
});

axios.get('https://example.com', { httpsAgent: agent })
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

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

const options = {
  hostname: 'example.com',
  port: 443,
  path: '/',
  method: 'GET',
  minVersion: 'TLSv1.2',
  maxVersion: 'TLSv1.3',
};

https.request(options, (res) => {
  console.log('Connected with:', res.socket.getProtocol());
  res.on('data', (d) => process.stdout.write(d));
}).end();

const tls = require('tls');
tls.DEFAULT_MIN_VERSION = 'TLSv1.2';

const https = require('https');

const options = {
  hostname: 'example.com',
  port: 443,
  path: '/',
  method: 'GET',
  ciphers: 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384',
  honorCipherOrder: true,
};

https.request(options, (res) => {
  console.log('Cipher:', res.socket.getCipher());
  res.on('data', (d) => process.stdout.write(d));
}).end();

node -e "console.log(require('tls').DEFAULT_CIPHERS)"

# Check current system time
date

# On Linux, sync with NTP
sudo ntpdate -s time.nist.gov

# Or use systemd-timesyncd
sudo timedatectl set-ntp true
timedatectl status

# On macOS
sudo sntp -sS time.apple.com

# Run Node.js with system CA certificates
node --use-openssl-ca app.js

# Or set environment variable
export NODE_OPTIONS="--use-openssl-ca"
node app.js

# Enable Node.js TLS debugging
NODE_DEBUG=tls node app.js

# Or use environment variable in code
process.env.NODE_DEBUG = 'tls';

Advanced notes

Frequently asked questions

What does "SSL_ERROR_BAD_HANDSHAKE" mean?

js failed to complete the TLS/SSL handshake process when establishing a secure connection. The TLS handshake is a multi-step negotiation where the client and server agree on protocol versions, cipher suites, exchange certificates, and generate encryption keys to create a secure session. When this handshake fails, it means the client and server were unable to find a mutually compatible configuration.

How do I fix "SSL_ERROR_BAD_HANDSHAKE"?

This error occurs when a Node.js client and server cannot establish a secure TLS/SSL connection during the handshake process. The handshake failure typically stems from protocol version mismatches, incompatible cipher suites, certificate validation issues, or misconfigured TLS settings.

What causes "SSL_ERROR_BAD_HANDSHAKE"?

Protocol version mismatch between client and server (e.g., server only supports TLS 1.0/1.1 while Node.js requires TLS 1.2+) No mutually supported cipher suites between client and server Server using self-signed certificates without proper CA configuration in Node.js

Is the "SSL_ERROR_BAD_HANDSHAKE" 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: no ciphers available (TLS cipher list is empty or invalid)

  No ciphers available - TLS cipher list is empty or invalid

  HIGH

• DeprecationWarning: util.pump is deprecated (use stream.pipe instead)

  DeprecationWarning: util.pump is deprecated (use stream.pipe instead)

  LOW

• Error: DH parameter is too small

  DH parameter is too small (Diffie-Hellman key too weak)

  HIGH

• TypeError: stream._write is not a function

  stream._write is not a function

  HIGH

• 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
• 📖
  TLS module and handshake error handling(Official Docs)
• 🐙
  SSL handshake errors in Node.js >= 8.6.0(GitHub)
• 📝
  TLS handshake failure debugging