karatelabs/karate · error · RuntimeException

failed to create client SSL context

Error message

failed to create client SSL context: <message>

What it means

SslContextFactory.createClientContext builds an SSLContext from the given SSL/TLS config (trust material, key managers, algorithm). Any failure during that construction is wrapped and rethrown as "failed to create client SSL context: <message>" with the original exception attached.

Solutions

1. Read the chained cause's message to identify the exact failure (missing file, bad password, bad algorithm) and fix the config value
2. Verify configured paths exist and are readable from the working directory/classpath, and passwords are correct
3. Validate the algorithm name (e.g. 'TLS' or 'TLSv1.2') is supported by the JVM (SSLContext.getDefaultAlgorithm())

Example fix

// before
* configure ssl = { trustStore: 'classpath:missing.jks', trustStorePassword: 'wrong' }
// after
* configure ssl = { trustStore: 'classpath:trusted.jks', trustStorePassword: 'changeit', algorithm: 'TLSv1.2' }

// pre-flight: confirm configured SSL material exists before creating the context
java.nio.file.Path ts = java.nio.file.Path.of(trustStorePath);
if (!java.nio.file.Files.isReadable(ts)) throw new IllegalStateException("trust store not readable: " + ts);
if (!List.of("TLS","TLSv1.2","TLSv1.3").contains(algorithm)) throw new IllegalStateException("unsupported algorithm: " + algorithm);

try { SslContextFactory.createClientContext(config); } catch (RuntimeException e) { throw new IllegalStateException("check ssl config: " + e.getCause(), e); }

When it happens

Trigger: Calling the HTTP client initialization with an SSL config whose trust store file is missing/unreadable, keystore password wrong, PEM is malformed, or algorithm name is invalid — any Exception in the try block.

Common situations: Typo in trustStore/keystore path; wrong keystore password; internal company CA file not mounted in the container; unsupported algorithm string like 'TLSvX'; corrupt or expired PEM files.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

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

Related errors

• failed to create server SSL context
• failed to generate self-signed certificate
• failed to generate Netty SSL context
• CONNECT_FAILED
• could not build the pooled client's SSL context

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/SslContextFactory.java:65

    private static final Logger logger = LogContext.RUNTIME_LOGGER;

    /**
     * Create an SSLContext for client use (connecting to HTTPS servers).
     */
    public static SSLContext createClientContext(SslConfig config) {
        try {
            if (config.isTrustAll()) {
                return createTrustAllContext(config.getAlgorithm());
            }

            TrustManager[] trustManagers = loadTrustManagers(config);
            KeyManager[] keyManagers = loadKeyManagers(config);

            SSLContext ctx = SSLContext.getInstance(config.getAlgorithm());
            ctx.init(keyManagers, trustManagers, new SecureRandom());
            return ctx;
        } catch (Exception e) {
            throw new RuntimeException("failed to create client SSL context: " + e.getMessage(), e);
        }
    }

    /**
     * Create an SSLContext for server use (accepting HTTPS connections).
     */
    public static SSLContext createServerContext(SslConfig config) {
        try {
            if (config.getCertPath() == null) {
                // Generate self-signed certificate
                return SslUtils.generateSelfSigned();
            }
            return loadFromPem(config.getCertPath(), config.getKeyPath(), config.getAlgorithm());
        } catch (Exception e) {
            throw new RuntimeException("failed to create server SSL context: " + e.getMessage(), e);
        }
    }

View on GitHub (pinned to a22eb90246)