TLS handshake failures are one of those Node.js problems that can be confusing at first because the application may never receive the request.
A client connects to an HTTPS endpoint, TLS negotiation starts, and the connection fails before the application gets a chance to process the request.
This can happen after a certificate change, a Node.js runtime update, a change in TLS settings, a proxy configuration change, or when an older client connects to a server with stricter security requirements.
The useful way to troubleshoot a TLS handshake failure is to identify which part of the connection is failing instead of immediately changing TLS settings.
This article explains how TLS handshakes work in a Node.js HTTPS application, how to identify common causes, and how to fix them without weakening the security configuration.
What Happens During a TLS Handshake
Before an HTTPS request reaches a Node.js application, the client and server establish a secure TLS connection.
A simplified flow looks like this:
Client
|
| ClientHello
v
Node.js HTTPS Server
|
| ServerHello + Certificate
v
Client
|
| Key Exchange
v
Secure TLS Connection
|
v
HTTP Request
The exact handshake depends on the TLS version and cryptographic configuration.
The important point is that the HTTP request happens after the TLS handshake.
If the handshake fails, code such as this may never execute:
server.on("request", (req, res) => {
console.log("Request received");
});
That is why application-level request logging can show nothing even though clients are reporting connection failures.
A Basic Node.js HTTPS Server
A typical HTTPS server can be created with Node.js like this:
const https = require("node:https");
const fs = require("node:fs");
const options = {
key: fs.readFileSync("./server.key"),
cert: fs.readFileSync("./server.crt")
};
const server = https.createServer(options, (req, res) => {
res.writeHead(200, {
"content-type": "text/plain"
});
res.end("Hello from Node.js");
});
server.listen(8443, () => {
console.log("HTTPS server listening on port 8443");
});
The application code itself may be completely correct while the TLS connection still fails.
That is because TLS configuration sits below the HTTP request handling layer.
First Identify Where the Failure Happens
Before changing anything, determine whether the failure occurs during:
- DNS resolution
- TCP connection
- TLS negotiation
- Certificate validation
- HTTP protocol negotiation
- Application request processing
This distinction saves considerable troubleshooting time.
A useful diagnostic model is:
DNS
↓
TCP
↓
TLS
↓
HTTP
↓
Application
If TLS fails, changing application routes or middleware will not solve the problem.
Check the Node.js Runtime Version
Start with the runtime.
node --version
Also check the runtime used in production rather than relying only on your local development environment.
The Node.js runtime controls the underlying TLS implementation and the OpenSSL version used by that runtime.
After a runtime update, TLS behavior can change because supported protocols, cipher suites, certificate handling, or security defaults may change.
This is especially important when an application communicates with older systems.
Check the Certificate and Private Key
A basic HTTPS configuration requires a matching private key and certificate.
For example:
const options = {
key: fs.readFileSync("/certs/server.key"),
cert: fs.readFileSync("/certs/server.crt")
};
If the certificate does not match the private key, the HTTPS server cannot establish the expected identity.
You can inspect the certificate with OpenSSL:
openssl x509 -in server.crt -text -noout
Check information such as:
- Subject
- Issuer
- Validity period
- Subject Alternative Name
- Public key
- Signature algorithm
For production HTTPS, the certificate's hostname coverage is particularly important.
Check the Certificate Chain
A server certificate may be valid by itself but still cause problems if the required intermediate certificates are not provided correctly.
A common mistake is configuring only the leaf certificate:
const options = {
key: privateKey,
cert: serverCertificate
};
Depending on the certificate provider, the server may need to send the appropriate certificate chain.
A typical configuration may look like:
const options = {
key: fs.readFileSync("./server.key"),
cert: fs.readFileSync("./server.crt"),
ca: fs.readFileSync("./ca-chain.crt")
};
The exact configuration depends on whether the application is acting as a server, client, or both.
Do not add a CA file simply because a TLS handshake failed. First determine what certificate validation problem actually exists.
Check Certificate Expiration
An expired certificate is an obvious but frequently overlooked cause of HTTPS problems.
Inspect the certificate:
openssl x509 -in server.crt -noout -dates
You should see the certificate's validity range.
For production systems, certificate expiration should be monitored automatically rather than discovered through client failures.
Check the Hostname
A certificate must normally cover the hostname used by the client.
For example, a certificate issued for:
api.example.com
does not automatically cover:
internal.example.com
unless the certificate's Subject Alternative Name includes it.
This becomes especially important when a new DNS record, load balancer, or API hostname is introduced.
Check TLS Protocol Versions
A common problem occurs when the client and server cannot agree on a TLS protocol version.
Node.js supports configurable TLS versions.
For example:
const options = {
minVersion: "TLSv1.2",
key: fs.readFileSync("./server.key"),
cert: fs.readFileSync("./server.crt")
};
A server should not enable obsolete TLS versions merely to make an old client work.
If an older client fails to connect, first identify what TLS version it supports.
You can inspect a server with OpenSSL:
openssl s_client -connect example.com:443 -tls1_2
Testing with a specific protocol version helps determine whether protocol negotiation is the problem.
Do Not Lower TLS Security as the First Fix
One of the most common troubleshooting mistakes is changing a secure configuration to accept older protocols or weaker settings without understanding the cause.
For example, changing:
minVersion: "TLSv1.2"
to an older protocol may make a legacy client connect.
But that does not mean the problem has been fixed correctly.
The better approach is:
- Identify the client's TLS capabilities.
- Identify the server's supported TLS versions.
- Determine whether the client can be upgraded.
- Determine whether compatibility can be handled at another layer.
- Keep the strongest practical security configuration.
Compatibility should be intentional.
Check Cipher Suite Compatibility
TLS also requires compatible cipher suites.
Node.js uses secure defaults, but applications can customize them.
For example:
const options = {
minVersion: "TLSv1.2",
ciphers: "ECDHE+AESGCM",
key: fs.readFileSync("./server.key"),
cert: fs.readFileSync("./server.crt")
};
Custom cipher configuration should be used carefully.
A server can accidentally remove the cipher suites required by legitimate clients.
Before changing the cipher list, check whether the application actually needs custom cipher configuration.
In many applications, the default Node.js configuration is safer and easier to maintain.
Check Server Name Indication
Server Name Indication, commonly called SNI, allows a client to indicate which hostname it wants during the TLS handshake.
This matters when multiple HTTPS domains share the same server or load balancer.
For example:
Client
|
| SNI: api.example.com
v
TLS Server
|
+-- api.example.com certificate
+-- admin.example.com certificate
If SNI routing is incorrect, the server may return the wrong certificate.
This can result in certificate validation errors even though the certificate itself is valid.
When multiple domains are hosted on the same infrastructure, check the SNI configuration before changing application code.
Check Mutual TLS Configuration
Some internal services use mutual TLS, where both sides authenticate each other.
In that setup:
Client Certificate
↓
Server
↓
Server Certificate
↓
Client
Node.js can be configured to request or require client certificates.
For example:
const options = {
key: fs.readFileSync("./server.key"),
cert: fs.readFileSync("./server.crt"),
requestCert: true,
rejectUnauthorized: true
};
If mutual TLS is enabled, a client certificate problem can appear as a TLS handshake failure.
Check:
- Client certificate expiration
- Client certificate issuer
- Server trust configuration
- Certificate chain
- Hostname validation
- Certificate permissions
Do not disable client certificate verification just to make the connection work.
Check Node.js HTTPS Client Errors
TLS problems can also happen when Node.js is the client.
For example:
const https = require("node:https");
https.get("https://api.example.com/data", (res) => {
console.log("Status:", res.statusCode);
}).on("error", (error) => {
console.error("HTTPS request failed:", error);
});
Useful error information can include:
error.code
error.message
error.reason
Log the relevant diagnostic information, but avoid logging credentials or sensitive request headers.
For example:
.on("error", (error) => {
console.error({
code: error.code,
message: error.message
});
});
This provides useful information without dumping the entire request object into logs.
Common Node.js TLS Errors
The exact error depends on the failure, but several error types appear frequently.
ECONNRESET
The connection was reset.
Possible causes include:
- Remote server closing the connection
- Proxy termination
- TLS negotiation failure
- Network infrastructure
- Server-side resource limits
Do not automatically assume ECONNRESET means a certificate problem.
CERT_HAS_EXPIRED
The certificate is expired.
Check the certificate's validity period and the certificate chain.
UNABLE_TO_VERIFY_LEAF_SIGNATURE
Node.js could not establish a trusted certificate chain.
Check whether the server is providing the correct intermediate certificates and whether the client trusts the issuing CA.
DEPTH_ZERO_SELF_SIGNED_CERT
The certificate is self-signed and is not trusted by the client.
This can be normal in development but is generally not appropriate for a public production endpoint.
ERR_TLS_CERT_ALTNAME_INVALID
The certificate does not match the hostname being used.
Check the Subject Alternative Name values in the certificate.
Test the Server Outside the Application
When troubleshooting TLS, test the endpoint independently of your application.
OpenSSL is useful for this:
openssl s_client -connect example.com:443 -servername example.com
The SNI parameter is important when the server hosts multiple domains.
You can inspect:
- Certificate chain
- TLS protocol
- Cipher
- Handshake status
- Certificate verification
This helps determine whether the problem is at the server TLS layer or inside application code.
Compare Working and Failing Clients
If one client works while another fails, compare their TLS capabilities.
For example:
Working client
TLS 1.3
Modern cipher
Valid certificate trust
Failing client
TLS 1.2 only
Older cipher support
Different trust store
This comparison is often more useful than changing the Node.js server configuration blindly.
Check:
- Operating system
- Node.js version
- OpenSSL version
- TLS versions
- Cipher support
- CA certificates
- Proxy configuration
Check Reverse Proxies
A Node.js application may not be directly exposed to the internet.
A common architecture is:
Client
|
| HTTPS
v
Load Balancer
|
| HTTPS
v
Node.js
Or:
Client
|
| HTTPS
v
Load Balancer
|
| HTTP
v
Node.js
These architectures have very different TLS responsibilities.
If TLS terminates at the load balancer, a certificate problem there may have nothing to do with Node.js HTTPS configuration.
Always identify where TLS termination occurs.
Check Environment Variables and Secrets
Production HTTPS configuration often comes from environment variables or mounted secrets.
For example:
const options = {
key: process.env.TLS_PRIVATE_KEY,
cert: process.env.TLS_CERTIFICATE
};
A deployment problem can cause the application to load an incorrect certificate.
Check:
- Secret names
- Secret versions
- Mounted files
- File permissions
- Environment-specific configuration
- Certificate rotation
A certificate rotation process should update the certificate and private key together.
Handle Certificate Rotation Carefully
Certificate renewal can cause temporary outages if the new certificate and private key are mismatched.
A safer process is:
New Certificate
+
Matching Private Key
↓
Validate
↓
Deploy
↓
Reload / Restart
↓
Verify HTTPS
Validate the certificate before replacing the active configuration.
For example:
openssl x509 -in new-server.crt -text -noout
Then verify that the certificate matches the private key.
Review TLS Settings During Node.js Upgrades
A Node.js runtime upgrade can expose compatibility problems that were hidden by older TLS behavior.
After upgrading the runtime, test:
- HTTPS inbound connections
- HTTPS outbound connections
- Internal service communication
- Mutual TLS
- Certificate validation
- HTTP/2 if enabled
- Proxy connections
- TLS monitoring
Do not assume that successful application startup means TLS compatibility is complete.
Troubleshooting Checklist
Problem | What to Check |
|---|
Certificate error | Certificate validity and hostname |
Trust failure | CA and intermediate certificates |
Handshake failure | TLS protocol compatibility |
Cipher error | Client and server cipher support |
Wrong certificate | SNI and proxy configuration |
Client certificate failure | Mutual TLS configuration |
ECONNRESET | Proxy, server, network, and TLS behavior |
Works locally but not in production | Production certificates and runtime |
Works with one client only | Client TLS capabilities |
Failure after deployment | Runtime and TLS configuration changes |
Common Mistakes
Disabling Certificate Validation
Avoid code like:
process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
This disables certificate verification and can hide the actual problem.
It should not be used as a production fix.
Using rejectUnauthorized: false
This has the same basic problem when used to bypass certificate verification.
If certificate validation fails, fix the certificate trust problem instead.
Copying Old TLS Configuration
Security configurations copied from older applications may no longer be appropriate.
Review the configuration against the supported Node.js runtime rather than assuming old settings are still necessary.
Changing Multiple TLS Settings at Once
If you change protocol versions, cipher lists, certificate files, proxy settings, and trust stores simultaneously, it becomes difficult to identify the actual cause.
Change one logical area at a time and test after each change.
Testing Only Through a Browser
Browsers hide many TLS details.
Use command-line tools and application logs to inspect the actual handshake behavior.
A Practical Troubleshooting Process
When a Node.js HTTPS application starts reporting TLS handshake failures, use this sequence.
Step 1: Capture the Error
Record the exact error code and message.
Step 2: Determine the Connection Direction
Is Node.js receiving HTTPS traffic or making an outbound HTTPS request?
Step 3: Identify the TLS Endpoint
Determine whether TLS terminates at Node.js, a proxy, a load balancer, or another service.
Step 4: Check the Certificate
Verify the certificate, hostname, expiration, and chain.
Step 5: Check the Node.js Runtime
Confirm the production Node.js version.
Step 6: Test With OpenSSL
Use an independent TLS client to inspect the handshake.
Step 7: Compare Clients
Determine whether the failure affects all clients or only specific clients.
Step 8: Check TLS Compatibility
Review protocol versions, cipher suites, SNI, and mutual TLS requirements.
Step 9: Test in Staging
Reproduce the issue outside production whenever possible.
Step 10: Deploy the Smallest Safe Fix
Avoid weakening TLS security simply to restore compatibility.
Advantages of Keeping TLS Configuration Simple
A simple TLS configuration has several practical benefits:
- Easier troubleshooting
- Fewer compatibility surprises
- Lower maintenance overhead
- Easier certificate rotation
- Less configuration drift
- Better alignment with Node.js defaults
Custom TLS settings are sometimes necessary, particularly for enterprise integrations and mutual TLS.
But every custom setting should have a reason.
Summary
TLS handshake failures occur before normal HTTP request processing, which is why they can be difficult to troubleshoot from application logs alone.
The most effective approach is to work from the connection layers upward.
Start with DNS and TCP, confirm where TLS terminates, inspect the certificate and trust chain, check TLS protocol compatibility, and then review Node.js configuration.
If the problem appeared after a Node.js upgrade, certificate rotation, proxy change, or security configuration change, compare the old and new environments rather than immediately weakening the TLS configuration.
Most importantly, do not disable certificate validation or enable older protocols simply because they make the error disappear. A successful connection is not a useful fix if it removes the security properties that HTTPS is supposed to provide.
A good TLS troubleshooting process should leave the application both working and correctly secured.
Join the conversation! Your thoughts help the community grow.