karatelabs/karate · error · WsException

CONNECT_FAILED

CONNECT_FAILED

Error message

SSL context creation failed

What it means

WsClient.doConnect builds a Netty SSLContext with an insecure trust manager when trustAllCerts is enabled. If building that SslContext throws SSLException, it is wrapped in a WsException with Type.CONNECT_FAILED. This means the TLS client stack could not be initialized, not that the server rejected the connection.

Solutions

1. Inspect the wrapped SSLException cause for the exact algorithm/provider failure.
2. Ensure a supported JDK (8u252+/11+) with working SunJSSE; check jdk.tls.disabledAlgorithms in java.security.
3. Avoid trustAllCerts in production — configure a real trust store, which uses the default SSL path.
4. Check native TLS provider issues (add/remove netty-tcnative dependency) or force the JDK provider.
5. Retry after fixing the JVM security configuration; this is not a transient network error.

Example fix

// before (fails in restricted JVM)
options.setTrustAllCerts(true);
// after
options.setSslContext(customSslContextWithTrustStore); // avoid insecure builder path

// Java
boolean cryptoOk;
try { javax.net.ssl.SSLContext.getDefault(); cryptoOk = true; } catch (Exception e) { cryptoOk = false; }

try {
    ws.connect();
} catch (WsException e) {
    if (e.getType() == WsException.Type.CONNECT_FAILED && e.getMessage().contains("SSL context creation failed")) {
        throw new IllegalStateException("TLS provider misconfiguration", e.getCause());
    }
    throw e;
}

When it happens

Trigger: Connecting a WebSocket with options.isTrustAllCerts() == true while SslContextBuilder.forClient().trustManager(InsecureTrustManagerFactory.INSTANCE).build() throws — e.g. missing TLS provider, unavailable ALPN/OpenSSL natives, or JDK TLS restrictions.

Common situations: netty-tcnative/openssl availability problems; FIPS-restricted JVMs disabling the required algorithms; corrupted JDK security config (java.security, excluded algorithms); very old JDK combined with newer Netty TLS requirements.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• failed to generate Netty SSL context
• failed to create client SSL context
• failed to create server SSL context
• failed to generate self-signed certificate
• failed to create SSL context from files

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/1326c04cbbea3401. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/http/WsClient.java:164

        }
    }

    private void doConnect() {
        URI uri = options.getUri();
        String scheme = uri.getScheme();
        String host = options.getHost();
        int port = options.getPort();

        SslContext sslContext = null;
        if (options.isSsl()) {
            sslContext = options.getSslContext();
            if (sslContext == null && options.isTrustAllCerts()) {
                try {
                    sslContext = SslContextBuilder.forClient()
                            .trustManager(InsecureTrustManagerFactory.INSTANCE)
                            .build();
                } catch (SSLException e) {
                    throw new WsException(WsException.Type.CONNECT_FAILED, "SSL context creation failed", e);
                }
            }
        }

        HttpHeaders headers = new DefaultHttpHeaders();
        for (Map.Entry<String, String> entry : options.getHeaders().entrySet()) {
            headers.add(entry.getKey(), entry.getValue());
        }

        WebSocketClientHandshaker handshaker = WebSocketClientHandshakerFactory.newHandshaker(
                uri,
                WebSocketVersion.V13,
                options.getSubProtocol(),
                options.isCompression(),
                headers,
                options.getMaxPayloadSize()
        );

View on GitHub (pinned to a22eb90246)