{"record":{"id":"8631829cc33642be","repo":"karatelabs/karate","slug":"failed-to-generate-netty-ssl-context-message","errorCode":null,"errorMessage":"failed to generate Netty SSL context: <message>","messagePattern":"failed to generate Netty SSL context: <message>","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/SslUtils.java","lineNumber":102,"sourceCode":"        } catch (Exception e) {\n            throw new RuntimeException(\"failed to generate self-signed certificate: \" + e.getMessage(), e);\n        }\n    }\n\n    /**\n     * Generate a Netty SslContext for server use.\n     */\n    public static SslContext generateNettySslContext() {\n        try {\n            java.util.Date notBefore = new java.util.Date();\n            java.util.Date notAfter = new java.util.Date(notBefore.getTime() + (86400000L * VALIDITY_DAYS));\n\n            @SuppressWarnings(\"deprecation\")\n            SelfSignedCertificate ssc = new SelfSignedCertificate(\"localhost\", notBefore, notAfter);\n\n            return SslContextBuilder.forServer(ssc.certificate(), ssc.privateKey()).build();\n        } catch (Exception e) {\n            throw new RuntimeException(\"failed to generate Netty SSL context: \" + e.getMessage(), e);\n        }\n    }\n\n    /**\n     * Create a Netty SslContext from PEM files.\n     */\n    public static SslContext createNettySslContext(File certFile, File keyFile) {\n        try {\n            return SslContextBuilder.forServer(certFile, keyFile).build();\n        } catch (Exception e) {\n            throw new RuntimeException(\"failed to create SSL context from files: \" + e.getMessage(), e);\n        }\n    }\n\n    /**\n     * Create a Netty SslContext from PEM file paths.\n     */\n    public static SslContext createNettySslContext(String certPath, String keyPath) {","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/SslUtils.java#L84-L120","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the cause chain (getCause()) — the wrapped message names the real crypto/provider failure","Ensure the JVM has default JCE policy (unlimited crypto) and is not in restricted FIPS mode","Upgrade Netty (io.netty:netty-handler) to a version compatible with your JDK","Check that notBefore < notAfter and both are valid Instant values if passed programmatically","As a workaround, supply your own certificate via SslUtils.createNettySslContext(certFile, keyFile) instead of self-signed generation"],"exampleFix":"// before: server fails to start with self-signed cert on restricted JVM\nMockServer.feature(...).httpsEnabled(true).build();\n// after: provide explicit PEM cert/key so self-signed generation is skipped\nMockServer.feature(...)\n    .httpsEnabled(true)\n    .certFile(\"classpath:server.crt\")\n    .keyFile(\"classpath:server.key\")\n    .build();","handlingStrategy":"try-catch","validationCode":"// ensure JDK crypto is usable before enabling HTTPS mock server\ntry { javax.crypto.Cipher.getInstance(\"AES\"); } catch (Exception e) { throw new IllegalStateException(\"JCE unavailable\", e); }","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["Keep Netty handler version aligned with the JDK","Avoid custom notBefore/notAfter unless necessary","Test HTTPS mock startup in CI containers early"],"tags":["ssl","netty","certificate","tls"],"backgroundTag":"module-init-failed","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}