karatelabs/karate · error · RuntimeException

failed to create server SSL context

Error message

failed to create server SSL context: <message>

What it means

SslContextFactory.createServerContext creates an SSLContext for a Karate mock/HTTPS server. If a certPath is provided it loads from PEM; otherwise it generates a self-signed cert. Any exception in either path is wrapped as "failed to create server SSL context: <message>".

Solutions

1. Check the chained cause message; verify certPath/keyPath point to valid, readable PEM files and match each other
2. If you don't need custom certs, remove certPath so Karate generates a self-signed certificate
3. Test key/cert loading with openssl (e.g. `openssl x509 -in cert.pem`, `openssl pkey -in key.pem`) to confirm validity

Example fix

// before
* configure ssl = { certPath: 'certs/server.pem', keyPath: 'certs/wrong.key' }
// after
* configure ssl = { certPath: 'certs/server.crt', keyPath: 'certs/server.key' }

if (config.getCertPath() != null) {
    if (!java.nio.file.Files.isReadable(java.nio.file.Path.of(config.getCertPath())))
        throw new IllegalStateException("cert not readable: " + config.getCertPath());
    if (!java.nio.file.Files.isReadable(java.nio.file.Path.of(config.getKeyPath())))
        throw new IllegalStateException("key not readable: " + config.getKeyPath());
}

try { server = karate.start(mock, sslConfig); } catch (RuntimeException e) { if (e.getMessage().startsWith("failed to create server SSL context")) { /* validate PEM files with openssl */ } throw e; }

When it happens

Trigger: Starting an HTTPS mock server (karate.start with ssl: true) where the PEM cert/key files are missing, unreadable, or malformed, or the self-signed generation fails (e.g. missing crypto provider).

Common situations: Typo in certPath/keyPath; PEM files with wrong permissions in containers; encrypted PEM keys with unsupported passphrase handling; JRE lacking the classes needed for self-signed generation.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

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

Related errors

• failed to generate self-signed certificate
• failed to create client SSL context
• failed to load private key: unsupported algorithm
• failed to generate Netty SSL context
• failed to create SSL context from files

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

Appendix: source

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

            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);
        }
    }

    /**
     * Create a trust-all SSLContext (accepts any certificate).
     */
    private static SSLContext createTrustAllContext(String algorithm) throws Exception {
        TrustManager[] trustManagers = new TrustManager[]{
            new X509TrustManager() {
                @Override
                public void checkClientTrusted(X509Certificate[] chain, String authType) {
                }

                @Override
                public void checkServerTrusted(X509Certificate[] chain, String authType) {
                }

                @Override

View on GitHub (pinned to a22eb90246)