How to fix Error: UNSUPPORTED_PROTOCOL: TLS version mismatch (incompatible protocol versions) in Node.js

Node.jsINTERMEDIATEHIGHUpdated Dec 9, 2025· 151 views

This error occurs when a Node.js client attempts to connect to a server using incompatible TLS/SSL protocol versions. The TLS handshake fails because the client and server cannot agree on a mutually supported protocol version.

Quick fix

Fixes UNSUPPORTED_PROTOCOL

node -p "process.versions.openssl"
node -p "require('tls').DEFAULT_MIN_VERSION"
node -p "require('tls').DEFAULT_MAX_VERSION"
  1. Check Node.js and server TLS versions
  2. Configure minVersion and maxVersion in your code
  3. Use command-line flags for application-wide TLS settings
  4. Update server TLS configuration (preferred long-term solution)
node.js — error
node -p "process.versions.openssl"
node -p "require('tls').DEFAULT_MIN_VERSION"
node -p "require('tls').DEFAULT_MAX_VERSION"
Error: UNSUPPORTED_PROTOCOL: TLS version mismatch (incompatible protocol versions)

What this error means

The UNSUPPORTED_PROTOCOL error indicates that the TLS (Transport Layer Security) version negotiation between your Node.js application and a remote server has failed. This happens during the SSL/TLS handshake when the client and server try to agree on a protocol version to use for secure communication. Node.js 12 and later versions default to TLS 1.2 as the minimum supported protocol version for security reasons. When your application tries to connect to a server that only supports older protocols (like TLS 1.0 or 1.1), or when a server requires a newer protocol version that your Node.js version doesn't support, the connection fails with this error. The error message often appears as "ssl_choose_client_version:unsupported protocol" in the underlying OpenSSL error stack, indicating that the SSL library couldn't select a compatible protocol version during the client-server negotiation.

Typical symptoms

  • HTTPS requests fail immediately with UNSUPPORTED_PROTOCOL error
  • Connection attempts to legacy servers fail after Node.js upgrade
  • Error occurs specifically during TLS handshake phase
  • Third-party API connections fail with protocol errors
  • Database connections over SSL fail to establish
  • Error message includes "ssl_choose_client_version:unsupported protocol"

Common causes

  1. Server only supports TLS 1.0 or 1.1, which are disabled by default in Node.js 12+
  2. Node.js version is too old to support TLS 1.3 required by the server
  3. Explicit secureProtocol configuration specifies incompatible protocol version
  4. Server has strict TLS requirements that exclude Node.js default protocol versions
  5. Cipher suite mismatch prevents protocol negotiation
  6. Firewall or proxy intercepting and modifying TLS handshake

How to fix "Error: UNSUPPORTED_PROTOCOL: TLS version mismatch (incompatible protocol versions)"

1Check Node.js and server TLS versions

First, identify which TLS versions your Node.js installation supports and which the server requires.

Check Node.js TLS support:

bash
node -p "process.versions.openssl"
node -p "require('tls').DEFAULT_MIN_VERSION"
node -p "require('tls').DEFAULT_MAX_VERSION"

Test the server's TLS support using OpenSSL:

bash
# Test TLS 1.0
openssl s_client -connect example.com:443 -tls1

# Test TLS 1.1
openssl s_client -connect example.com:443 -tls1_1

# Test TLS 1.2
openssl s_client -connect example.com:443 -tls1_2

# Test TLS 1.3
openssl s_client -connect example.com:443 -tls1_3

This helps you understand which protocol versions are available and where the incompatibility lies.

2Configure minVersion and maxVersion in your code

The recommended approach is to explicitly set the TLS version range in your HTTPS requests using minVersion and maxVersion options.

For HTTPS requests:

javascript
const https = require('https');

const options = {
  hostname: 'example.com',
  port: 443,
  path: '/',
  method: 'GET',
  // Set minimum TLS version (e.g., to allow TLS 1.0 for legacy servers)
  minVersion: 'TLSv1',
  // Or set a specific secure protocol
  // secureProtocol: 'TLSv1_2_method'
};

https.request(options, (res) => {
  console.log('Connection successful');
}).end();

For HTTPS agents (reusable connections):

javascript
const https = require('https');

const agent = new https.Agent({
  minVersion: 'TLSv1.2',
  maxVersion: 'TLSv1.3'
});

https.get('https://example.com', { agent }, (res) => {
  console.log('Connected with TLS version:', res.socket.getProtocol());
});

For Axios or other libraries:

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

const instance = axios.create({
  httpsAgent: new https.Agent({
    minVersion: 'TLSv1.2'
  })
});

instance.get('https://example.com')
  .then(response => console.log('Success'))
  .catch(error => console.error('Error:', error.message));
3Use command-line flags for application-wide TLS settings

If you need to change TLS behavior for your entire application without modifying code, use Node.js command-line flags.

Allow TLS 1.0 (for legacy server compatibility):

bash
node --tls-min-v1.0 app.js

Enforce TLS 1.2 minimum:

bash
node --tls-min-v1.2 app.js

Set maximum TLS version:

bash
node --tls-max-v1.2 app.js

Combine with other flags:

bash
node --tls-min-v1.0 --tls-max-v1.2 app.js

You can also set these in your package.json scripts:

json
{
  "scripts": {
    "start": "node --tls-min-v1.0 app.js"
  }
}

Note: The --tls-v1.0 flag format used in older Node.js versions has been deprecated in favor of --tls-min-v1.0.

4Update server TLS configuration (preferred long-term solution)

Rather than downgrading client security, the best solution is to upgrade the server to support modern TLS versions.

For servers you control, enable TLS 1.2 and 1.3:

Nginx:

nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;

Apache:

apache
SSLProtocol -all +TLSv1.2 +TLSv1.3
SSLCipherSuite HIGH:!aNULL:!MD5

Node.js HTTPS server:

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

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
  minVersion: 'TLSv1.2',
  maxVersion: 'TLSv1.3'
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('Secure connection\n');
}).listen(443);

After updating the server configuration, restart the service and test the connection from your Node.js client without special TLS flags.

5Verify the connection works

After implementing your fix, verify that the TLS connection succeeds and uses the expected protocol version.

Test your connection and log the TLS version:

javascript
const https = require('https');

const options = {
  hostname: 'example.com',
  port: 443,
  path: '/',
  method: 'GET'
};

const req = https.request(options, (res) => {
  console.log('Connection successful!');
  console.log('TLS Version:', res.socket.getProtocol());
  console.log('Cipher:', res.socket.getCipher());

  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

req.on('error', (e) => {
  console.error('Connection failed:', e.message);
});

req.end();

Expected output for a successful TLS 1.2 connection:

bash
Connection successful!
TLS Version: TLSv1.2
Cipher: { name: 'ECDHE-RSA-AES128-GCM-SHA256', version: 'TLSv1.2' }

Advanced notes

Security Considerations:
Downgrading to TLS 1.0 or 1.1 should only be a temporary solution for legacy system compatibility. These protocols have known vulnerabilities and are deprecated. PCI DSS compliance requires TLS 1.2 or higher for payment processing systems.

OpenSSL Version Impact:
Node.js TLS support depends on the underlying OpenSSL version. Older Node.js versions compiled against older OpenSSL may not support TLS 1.3. Check your OpenSSL version with node -p "process.versions.openssl".

AWS SDK Specific Configuration:
If you're using AWS SDK for JavaScript, you can enforce TLS 1.2 globally:

javascript
const AWS = require('aws-sdk');
const https = require('https');

AWS.config.update({
  httpOptions: {
    agent: new https.Agent({
      minVersion: 'TLSv1.2'
    })
  }
});

Cipher Suite Compatibility:
Sometimes the protocol version matches but cipher suites don't. If you continue having issues after setting minVersion, try specifying compatible ciphers:

javascript
const agent = new https.Agent({
  minVersion: 'TLSv1.2',
  ciphers: 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384'
});

Docker and Container Environments:
Base images with outdated OpenSSL versions can cause TLS issues. Use recent base images like node:18-alpine or node:20 that include modern OpenSSL versions with full TLS 1.3 support.

Frequently asked questions

What does "UNSUPPORTED_PROTOCOL" mean?
js application and a remote server has failed. This happens during the SSL/TLS handshake when the client and server try to agree on a protocol version to use for secure communication. 2 as the minimum supported protocol version for security reasons.
How do I fix "UNSUPPORTED_PROTOCOL"?
This error occurs when a Node.js client attempts to connect to a server using incompatible TLS/SSL protocol versions. The TLS handshake fails because the client and server cannot agree on a mutually supported protocol version.
What causes "UNSUPPORTED_PROTOCOL"?
Server only supports TLS 1.0 or 1.1, which are disabled by default in Node.js 12+ Node.js version is too old to support TLS 1.3 required by the server Explicit secureProtocol configuration specifies incompatible protocol version
Is the "UNSUPPORTED_PROTOCOL" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading