{"record":{"id":"f564518577460138","repo":"eclipse-vertx/vert.x","slug":"failed-to-initialize-the-keystore","errorCode":null,"errorMessage":"Failed to initialize the keystore","messagePattern":"Failed to initialize the keystore","errorType":"exception","errorClass":"KeyStoreException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/net/impl/KeyStoreHelper.java","lineNumber":438,"sourceCode":"   * @return keystore instance\n   *\n   * @throws KeyStoreException if the underlying engine cannot create an instance\n   */\n  private static KeyStore createEmptyKeyStore() throws KeyStoreException {\n    final KeyStore keyStore;\n    String defaultKeyStoreType = KeyStore.getDefaultType();\n\n    if (defaultKeyStoreType.equalsIgnoreCase(\"jks\") && Security.getAlgorithms(\"KeyStore\").contains(\"PKCS12\")) {\n      keyStore = KeyStore.getInstance(\"PKCS12\");\n    } else {\n      keyStore = KeyStore.getInstance(defaultKeyStoreType);\n    }\n    try {\n      keyStore.load(null, null);\n    } catch (CertificateException | NoSuchAlgorithmException | IOException e) {\n      // these exceptions should never be thrown as there is no initial data\n      // provided to the initialization of the keystore\n      throw new KeyStoreException(\"Failed to initialize the keystore\", e);\n    }\n    return keyStore;\n  }\n}\n","sourceCodeStart":420,"sourceCodeEnd":443,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/net/impl/KeyStoreHelper.java#L420-L443","documentation":"createEmptyKeyStore() initializes an in-memory KeyStore via keyStore.load(null, null) to build a temporary trust/keystore. Although this should never fail for empty input, any CertificateException/NoSuchAlgorithmException/IOException is wrapped in KeyStoreException('Failed to initialize the keystore'). It indicates a JVM/provider level problem with the keystore implementation, not user data.","triggerScenarios":"Instantiating keyCertOptions/trustOptions that rely on an internally created keystore (e.g. PEM-based options build an empty keystore to load certs into) when the JCA provider misbehaves — broken java.security config, missing provider, or corrupted JVM security files.","commonSituations":"Customized/restricted java.security (disabled providers); stripped-down container JREs missing security providers; FIPS misconfiguration.","solutions":["Check the JVM's java.security file was not modified to remove standard providers (SUN, SunJSSE).","Run in a stock JDK/JRE image rather than a stripped JRE; verify with a minimal KeyStore.getInstance(\"JKS\") test.","Remove FIPS/policy flags (-Djava.security.debug can help diagnose) if incorrectly set.","Report upstream if it reproduces on an unmodified JDK, including the cause exception."],"exampleFix":"// before\njava -Djava.security.properties=custom.security -jar app.jar // removed providers\n// after\njava -jar app.jar // default security config","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  vertx.createHttpServer(options).listen();\n} catch (VertxException e) {\n  if (e.getCause() instanceof KeyStoreException) {\n    log.error(\"JCA keystore init failed — check java.security providers\", e.getCause());\n  }\n  throw e;\n}","preventionTips":["Do not strip security providers from container JREs","Avoid custom java.security overrides unless required and tested","Pin to standard JDK images in CI and production","Test TLS setup at startup rather than lazily on first request"],"tags":["jvm","keystore","ssl","provider"],"backgroundTag":"module-init-failed","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}