karatelabs/karate · error · RuntimeException

failed to generate Netty SSL context

Error message

failed to generate Netty SSL context: <message>

What it means

Karate wraps any exception thrown while building a self-signed Netty SSL certificate/context into this RuntimeException. The self-signed certificate generation (via Netty's SelfSignedCertificate) or the subsequent SslContextBuilder.build() failed, e.g. due to invalid date ranges or a JVM security/crypto problem. The original cause is preserved as the suppressed cause for diagnosis.

Solutions

1. Read the cause chain (getCause()) — the wrapped message names the real crypto/provider failure
2. Ensure the JVM has default JCE policy (unlimited crypto) and is not in restricted FIPS mode
3. Upgrade Netty (io.netty:netty-handler) to a version compatible with your JDK
4. Check that notBefore < notAfter and both are valid Instant values if passed programmatically
5. As a workaround, supply your own certificate via SslUtils.createNettySslContext(certFile, keyFile) instead of self-signed generation

Example fix

// before: server fails to start with self-signed cert on restricted JVM
MockServer.feature(...).httpsEnabled(true).build();
// after: provide explicit PEM cert/key so self-signed generation is skipped
MockServer.feature(...)
    .httpsEnabled(true)
    .certFile("classpath:server.crt")
    .keyFile("classpath:server.key")
    .build();

// ensure JDK crypto is usable before enabling HTTPS mock server
try { javax.crypto.Cipher.getInstance("AES"); } catch (Exception e) { throw new IllegalStateException("JCE unavailable", e); }

try { server = MockServer.feature(f).httpsEnabled(true).build(); } catch (RuntimeException e) { if (e.getMessage().startsWith("failed to generate Netty SSL context")) { log.error("TLS init failed", e.getCause()); } throw e; }

When it happens

Trigger: Calling generateNettySslContext (indirectly via Karate's mock/HTTPS server startup with self-signed TLS) when SelfSignedCertificate construction throws — invalid notBefore/notAfter dates, weak crypto policy, or the SslContextBuilder.build() fails to initialize OpenSSL/JDK SSL provider.

Common situations: Starting a Karate mock server with httpsEnabled=true in a container with restricted /dev/urandom or FIPS-mode JVM; PKIX provider misconfiguration; extreme date arguments passed programmatically; old Netty versions incompatible with the JVM.

Understand the failure class

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

Related errors

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

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/SslUtils.java:102

        } catch (Exception e) {
            throw new RuntimeException("failed to generate self-signed certificate: " + e.getMessage(), e);
        }
    }

    /**
     * Generate a Netty SslContext for server use.
     */
    public static SslContext generateNettySslContext() {
        try {
            java.util.Date notBefore = new java.util.Date();
            java.util.Date notAfter = new java.util.Date(notBefore.getTime() + (86400000L * VALIDITY_DAYS));

            @SuppressWarnings("deprecation")
            SelfSignedCertificate ssc = new SelfSignedCertificate("localhost", notBefore, notAfter);

            return SslContextBuilder.forServer(ssc.certificate(), ssc.privateKey()).build();
        } catch (Exception e) {
            throw new RuntimeException("failed to generate Netty SSL context: " + e.getMessage(), e);
        }
    }

    /**
     * Create a Netty SslContext from PEM files.
     */
    public static SslContext createNettySslContext(File certFile, File keyFile) {
        try {
            return SslContextBuilder.forServer(certFile, keyFile).build();
        } catch (Exception e) {
            throw new RuntimeException("failed to create SSL context from files: " + e.getMessage(), e);
        }
    }

    /**
     * Create a Netty SslContext from PEM file paths.
     */
    public static SslContext createNettySslContext(String certPath, String keyPath) {

View on GitHub (pinned to a22eb90246)