What causes "Failed to initialize the keystore" in eclipse-vertx/vert.x?

Check the JVM's java.security file was not modified to remove standard providers (SUN, SunJSSE).

eclipse-vertx/vert.x · error · KeyStoreException

Failed to initialize the keystore

Error message

Failed to initialize the keystore

What it means

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.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/net/impl/KeyStoreHelper.java:438

   * @return keystore instance
   *
   * @throws KeyStoreException if the underlying engine cannot create an instance
   */
  private static KeyStore createEmptyKeyStore() throws KeyStoreException {
    final KeyStore keyStore;
    String defaultKeyStoreType = KeyStore.getDefaultType();

    if (defaultKeyStoreType.equalsIgnoreCase("jks") && Security.getAlgorithms("KeyStore").contains("PKCS12")) {
      keyStore = KeyStore.getInstance("PKCS12");
    } else {
      keyStore = KeyStore.getInstance(defaultKeyStoreType);
    }
    try {
      keyStore.load(null, null);
    } catch (CertificateException | NoSuchAlgorithmException | IOException e) {
      // these exceptions should never be thrown as there is no initial data
      // provided to the initialization of the keystore
      throw new KeyStoreException("Failed to initialize the keystore", e);
    }
    return keyStore;
  }
}

View on GitHub (pinned to fb308bd8c3)

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.

Example fix

// before
java -Djava.security.properties=custom.security -jar app.jar // removed providers
// after
java -jar app.jar // default security config

Defensive patterns

Strategy: try-catch

Try / catch

try {
  vertx.createHttpServer(options).listen();
} catch (VertxException e) {
  if (e.getCause() instanceof KeyStoreException) {
    log.error("JCA keystore init failed — check java.security providers", e.getCause());
  }
  throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: Customized/restricted java.security (disabled providers); stripped-down container JREs missing security providers; FIPS misconfiguration.

Related errors

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/f564518577460138. Report an issue: GitHub.