karate SSLHandshakeException in test environment: how to fix

TL;DR

Test environments usually serve self-signed or internal-CA certificates that Karate does not trust by default. Tell Karate to trust all certificates with the ssl config flag in the test setup, or point it at the right truststore. The handshake succeeds and the tests exercise the real API.

Error

karate SSLHandshakeException in test environment: how to fix

Karate feature fails with SSLHandshakeException: PKIX path building failed, against the test environment only.

Steps

1. Read the exception: PKIX path building failed means untrusted cert; other handshake errors may mean protocol mismatch. Expected output: you know it is trust, not TLS version.
2. Add the trust-all flag to the Karate config used by tests (configure ssl = true in karate-config.js or a Background step). Expected output: the flag is scoped to the test config, not production.
3. Re-run the failing feature. Expected output: the handshake completes and requests succeed.
4. If policy forbids trust-all, import the test CA into a truststore and point Karate at it instead. Expected output: the handshake trusts exactly the test CA.
5. Verify the flag never leaks into production test runs against real certificates. Expected output: prod-targeted runs still validate certificates strictly.

When to use

• Karate fails with SSLHandshakeException in test environments.
• Test env uses self-signed certificates.
• PKIX path building errors in Karate.

When not to use

• Production certificates fail (do not disable validation there).
• The error is a connection refusal (the server is not listening).
• You need mutual TLS (that is client cert config, a separate setup).

Variant phrasings

PKIX path building failed

The classic untrusted-cert error; trust-all or a proper truststore both resolve it.

SSL config ignored in called features

Configure calls in a called feature do not propagate the way Background steps do; set it in the shared config.

Mutual TLS in Karate

Client certificates need the keystore config alongside ssl; handshake failures there are client-auth, not server-trust.

Why it happens

Karate uses the JVM truststore, which knows public CAs but not your test environment's private CA. The handshake fails at certificate validation before any API logic runs, so the fix is entirely about trust, not about the API.

Edge cases

• Trust-all in a shared karate-config.js can leak into every environment; gate it behind an environment check.
• Certificate expiry in long-lived test environments produces the same exception months later; check dates when it recurs.
• Some proxies terminate TLS and present their own cert; the truststore needs the proxy CA, not the origin CA.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_vVs-xLF-Z3H3HNhO9G1Mbg

Resolved from the public thread: https://vectle.com/posts/pst_vVs-xLF-Z3H3HNhO9G1Mbg

Thread query: karate SSLHandshakeException in test environment: how to fix

TL;DR: Test environments usually serve self-signed or internal-CA certificates that Karate does not trust by default. Tell Karate to trust all certificates with the ssl config flag in the test setup, or point it at the right truststore. The handshake succeeds and the tests exercise the real API.