Quick Summary: Debugging Node.js TLS connection errors (ERR_TLS_CERT_ALTNAME_INVALID, ERR_TLS_SYSCALL_EG) in Docker on specific Linux distros when connecting to ...

Look, I've seen some garbage in my time. Memory leaks that brought down entire clusters, DNS resolution failures from hell, cascading failures that made Chernobyl look like a controlled burn. But this one? This was a special kind of insidious.

The Phantom TLS Failure: Node.js, ca-certificates, and the Ghost of OpenSSL 1.1.1 Legacy

You’re running a Node.js service in a container. It connects to an internal API. Most of the time, it works. Beautifully. Then, randomly, for some specific endpoints, it just… hangs. Or worse, it barfs up ERR_TLS_CERT_ALTNAME_INVALID or ERR_TLS_SYSCALL_EG. But only sometimes. And only in production. Never on your dev machine. Never in staging. Just when it counts. Infuriating.

The Symptom Profile

• Node.js service (typically 16.x or 18.x) running in a Docker container.
• Container base image is often Alpine Linux, sometimes specific Debian variants.
• TLS connection failures to internal, often legacy, APIs. Public APIs usually fine.
• Errors like ERR_TLS_CERT_ALTNAME_INVALID, ERR_TLS_SYSCALL_EG, or just connection timeouts.
• curl from within the container works perfectly against the problematic API.
• openssl s_client -connect problematic.api:443 -showcerts also works fine from inside the container.
• The certificate chain is verified as valid everywhere else.

You've checked everything. DNS. Firewall rules. Network ACLs. Proxy settings. System time. Container resource limits. You've even tried NODE_TLS_REJECT_UNAUTHORIZED=0 (don't you dare run that in production) just to confirm it's a certificate problem, which, of course, it is. But why is Node.js, specifically, choking?

The Trigger Environments

This obscure beast typically rears its head under these exact conditions. Pay attention, this table is your first clue.

Component	Fails On	Works On
OS/Base Image	Alpine Linux 3.14-3.16 (with glibc compatibility layer)	Alpine Linux 3.17+, Ubuntu 20.04+, Debian 11+
Node.js Version	16.x, 18.x (specifically builds bundled with OpenSSL 1.1.1 series)	20.x+ (OpenSSL 3.x), 14.x (OpenSSL 1.1.1, but often less problematic due to earlier build specifics)
Target API Server	Legacy services using specific Subject Alternative Names (SANs), older Certificate Authorities, or complex/custom certificate chains. Often Java 8/Tomcat 8, older HAProxy, or Nginx with specific cipher suites.	Modern services, public APIs with standard, widely-trusted CAs and simple chains.
Container Runtime Host Kernel	Docker/Containerd on kernel 5.4 - 5.10	Docker/Containerd on kernel 5.11+

The Root Cause

This isn't a certificate validity issue. Your certificates are fine. This is a subtle, agonizing interaction between Node.js's bundled OpenSSL 1.1.1 implementation, the system's ca-certificates package, and specific kernel network stack behaviors, especially exacerbated in certain containerized Alpine environments.

Here's the rub: Node.js 16.x and 18.x bundles OpenSSL 1.1.1. While this OpenSSL version is generally robust, its method of locating and trusting Certificate Authorities (CAs) can be finicky. Specifically, in certain Alpine Linux versions (3.14-3.16), the ca-certificates package, especially when combined with the glibc-compat layer often used with Node.js, can create a subtle inconsistency in how the ca-certificates.crt bundle is symlinked or rebuilt. Node's bundled OpenSSL sometimes struggles to correctly resolve the full trust chain from the system's bundle during the TLS handshake for specific, slightly complex certificate chains. This is particularly true for certificates that rely heavily on Subject Alternative Names (SANs) over Common Names, or older CAs that present their chain in a less-than-ideal order.

The ERR_TLS_CERT_ALTNAME_INVALID error, despite the SAN being correct, indicates that OpenSSL found the cert but failed to fully validate the chain or match the hostname in the final step of verification, likely due to an incomplete trust path from the system store. ERR_TLS_SYSCALL_EG is even worse; it’s a generic I/O error during the TLS handshake, often implying a fundamental breakdown in the secure channel setup, possibly due to a timeout from a stalled verification process. The specific kernel versions (5.4-5.10) compound this, as subtle timing differences or network stack optimizations can lead to handshake race conditions that are less forgiving with OpenSSL 1.1.1's CA resolution logic.

It's not that the certificate is bad. It's that OpenSSL 1.1.1, under these specific, obscure environmental pressures, struggles to build the trust path fast enough or correctly enough. You might even find parallels with how different backend frameworks handle complex network operations under load; for example, subtle performance differences between Spring Boot and NestJS can sometimes expose these underlying network stack quirks, though typically at a much higher throughput. This isn't about throughput, though; it's about sheer handshake integrity.

The Fix: Stop the Madness

The ultimate solution is simple: Upgrade. Get off Node 16/18 onto Node 20+ (which uses OpenSSL 3.x, far more robust in CA handling) and move to Alpine 3.17+ or a newer Debian/Ubuntu base. This sidesteps the problem entirely.

But if you're stuck in legacy hell, here's the specific incantation to at least paper over the cracks in your Alpine Node.js 16/18 Docker images. This forces Alpine to properly rebuild its CA bundle and ensures Node.js explicitly looks for it.

# Dockerfile snippet for Alpine-based Node.js 16.x/18.x images
# ONLY for when you're stuck with Node 16.x/18.x and Alpine 3.14-3.16 and hitting TLS issues.
# This should be inserted AFTER your base FROM instruction.

# Ensure ca-certificates are fully up-to-date and consistently linked.
# This rebuilds the /etc/ssl/certs/ca-certificates.crt symlink, ensuring
# Node.js's bundled OpenSSL 1.1.1 can reliably find and utilize the
# latest system trust store. This often resolves the intermittent
# ERR_TLS_CERT_ALTNAME_INVALID and ERR_TLS_SYSCALL_EG issues.
RUN apk update && \
    apk upgrade && \
    apk add --no-cache ca-certificates && \
    update-ca-certificates && \
    rm -rf /var/cache/apk/*

# Explicitly tell Node.js to use the system's CA bundle as a fallback.
# This can sometimes help OpenSSL 1.1.1 when it struggles to implicitly
# locate the correct trust chain, especially for complex or older CA structures.
ENV NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt

# Note: While this fix addresses CA pathing, ensuring strict clock synchronization
# (NTP) is also critical for TLS, especially in high-frequency environments.
# For more on reducing latency and ensuring robust timing, check out our guide on
# Decimating Latency: The Quant Developer's Guide to Sub-Millisecond Trading APIs.

This fix does two things: First, apk add --no-cache ca-certificates && update-ca-certificates ensures that Alpine's CA store is rebuilt and its central bundle (ca-certificates.crt) is correctly symlinked and updated. This is critical. Second, ENV NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt explicitly directs Node.js to use this known-good system bundle, bypassing some of the internal lookup woes that OpenSSL 1.1.1 sometimes experiences in these specific environments.

It's a band-aid. A necessary evil when you can't upgrade. This problem chewed up weeks of my life. Don't let it chew up yours. Just update your damn dependencies when you can.