Ballerina http:Client secureSocket: when verifyHostName=false hides a trust or DNS fault

Quick separation: exception type and TLS debug log

The reliable check before touching verifyHostName is the exception class and message thrown by the http:Client call:

• Trust-chain failure → SSLHandshakeException (wrapped by Ballerina) with messages like PKIX path building failed, unable to find valid certification path to requested target, or certificate_unknown. The handshake aborts during certificate validation.
• Hostname/DNS mismatch → SSLPeerUnverifiedException or CertificateException with explicit hostname text: Hostname 'api.example.com' not verified, Certificate for <host> doesn't match, or No subject alternative names matching IP address. The chain validated, but the presented certificate's SAN/CN does not cover the requested host.

Enable TLS debug logging to see the exact step without code changes:

ballerina run -Djavax.net.debug=ssl,handshake,trustmanager your_module.bal
# or set system property before client creation:
ballerina run -Dballerina.debug.tls=true your_module.bal

The handshake log shows "Certificate chain received" followed by either "Trust verification failed" (trust chain) or "Hostname verification failed" (DNS/hostname).

JVM DNS cache TTL: JDK-only, no Ballerina API

Ballerina does not expose a language-level setting for DNS cache TTL. The cache is controlled by standard JDK security properties that must be set at JVM startup:

• networkaddress.cache.ttl — positive cache TTL in seconds (default: -1 = cache forever when security manager present, otherwise implementation-specific).
• networkaddress.cache.negative.ttl — negative cache TTL (default: 10 seconds).

Apply them via Ballerina's JVM args:

ballerina run -Dnetworkaddress.cache.ttl=60 -Dnetworkaddress.cache.negative.ttl=5 your_module.bal
# or in Ballerina.toml:
[jvm]
args = ["-Dnetworkaddress.cache.ttl=60", "-Dnetworkaddress.cache.negative.ttl=5"]

These affect the entire Ballerina runtime process, not just the HTTP client. In containers the default is often -1 (indefinite caching) unless overridden.

Why pooled connections mask DNS changes

The http:Client uses a connection pool keyed by resolved IP. A DNS change after pool creation is invisible until:

• the pooled connection is evicted (idle timeout), or
• a new http:Client instance is created.

This makes DNS-related failures appear intermittent and timing-dependent.

Minimal diagnostic steps for your case

1. Run the failing call with -Djavax.net.debug=ssl,handshake,trustmanager and capture the handshake log.
2. Note the exception class: SSLHandshakeException = trust chain; SSLPeerUnverifiedException/CertificateException with hostname text = hostname mismatch.
3. If trust chain: verify the server's full chain is in the JVM default truststore or the secureSocket.cert truststore (JKS/PKCS12/PEM).
4. If hostname mismatch: check the resolved IP (dig +short hostname) and the certificate's SAN/CN (openssl s_client -connect host:443 -servername hostname).
5. If DNS caching is suspected, restart the Ballerina process with -Dnetworkaddress.cache.ttl=60 and retest.

One missing detail that changes the recommendation

Are you seeing the failure consistently on first call or only after the service has been running and DNS records changed? The answer determines whether to focus on truststore configuration (first call) or DNS cache/pool eviction (later calls).