eclipse-vertx/vert.x · error · VertxException

Missing X.509 certificate

Error message

Missing X.509 certificate

What it means

Keystore validation in KeyStoreHelper.loadKeyCert: more private keys than certificates were supplied, leaving at least one key without its X.509 certificate chain. The input at fault is the mismatched key/cert buffer lists from PemKeyCertOptions.

Source

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

    if (alias != null) {
      if (!ks.containsAlias(alias)) {
        throw new IllegalArgumentException("alias does not exist in the keystore: " + alias);
      }
      List<String> ksAliases = Collections.list(ks.aliases());
      for (String ksAlias : ksAliases) {
        if (!alias.equals(ksAlias)) {
          ks.deleteEntry(ksAlias);
        }
      }
    }
    return ks;
  }

  public static KeyStore loadKeyCert(List<Buffer> keyValue, List<Buffer> certValue) throws Exception {
    if (keyValue.size() < certValue.size()) {
      throw new VertxException("Missing private key");
    } else if (keyValue.size() > certValue.size()) {
      throw new VertxException("Missing X.509 certificate");
    }
    final KeyStore keyStore = createEmptyKeyStore();
    Iterator<Buffer> keyValueIt = keyValue.iterator();
    Iterator<Buffer> certValueIt = certValue.iterator();
    int index = 0;
    while (keyValueIt.hasNext() && certValueIt.hasNext()) {
      PrivateKey key = loadPrivateKey(keyValueIt.next());
      Certificate[] chain = loadCerts(certValueIt.next());
      keyStore.setEntry("dummy-entry-" + index++, new KeyStore.PrivateKeyEntry(key, chain), new KeyStore.PasswordProtection(DUMMY_PASSWORD.toCharArray()));
    }
    return keyStore;
  }

  private static PrivateKey loadPrivateKey(Buffer keyValue) throws Exception {
    if (keyValue == null) {
      throw new RuntimeException("Missing private key path");
    }
    KeyFactory rsaKeyFactory = KeyFactory.getInstance("RSA");

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Supply exactly one certificate per private key
2. Verify the PEM files include the full matching chain

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/net/impl/KeyStoreHelper.java:271 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

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