eclipse-vertx/vert.x · error · RuntimeException

Missing X.509 certificate path

Error message

Missing X.509 certificate path

What it means

loadCerts() throws 'Missing X.509 certificate path' when the Buffer passed for certificate loading is null. Callers of keyCertOptions certificate APIs hitting this means a null certificate path/value or buffer was supplied.

Source

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

        if (!beginDelimiter.equals(endDelimiter)) {
          throw new RuntimeException("Missing -----END " + beginDelimiter + "----- delimiter");
        } else {
          String content = pem.substring(beginMatcher.end(), endMatcher.start());
          content = content.replaceAll("\\s", "");
          if (content.length() == 0) {
            throw new RuntimeException("Empty pem file");
          }
          Collection<P> pemItems = pemFact.apply(endDelimiter, Base64.getDecoder().decode(content));
          pems.addAll(pemItems);
        }
      }
    }
    return pems;
  }

  private static X509Certificate[] loadCerts(Buffer buffer) throws Exception {
    if (buffer == null) {
      throw new RuntimeException("Missing X.509 certificate path");
    }
    CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
    List<X509Certificate> certs = loadPems(buffer, (delimiter, content) -> {
      try {
        switch (delimiter) {
          case "CERTIFICATE":
            return (Collection<X509Certificate>) certFactory.generateCertificates(new ByteArrayInputStream(content));
          default:
            return Collections.emptyList();
        }
      } catch (CertificateException e) {
        throw new VertxException(e);
      }
    });
    if (certs.isEmpty()) {
      throw new RuntimeException("Missing -----BEGIN CERTIFICATE----- delimiter");
    }
    return certs.toArray(new X509Certificate[0]);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Ensure setCertPath/setCertValue is called with a real path or PEM content before starting the server/client.
2. Resolve why the config property is null (missing key, unset env var) and provide a default.
3. Fail fast with an explicit check on the configured path before building options.
4. Point the path at the correct file and verify it exists on the classpath/filesystem.

Example fix

// before
String path = config.getString("cert"); // null
options.setCertPath(path);
// after
String path = config.getString("cert", "/etc/ssl/server.crt");
options.setCertPath(path);

Objects.requireNonNull(certPath, "TLS certificate path must be set");
if (!Files.exists(Path.of(certPath))) throw new IllegalStateException("Cert file missing: " + certPath);

boolean hasCertConfig(Vertx keyCertOptions o) {
  return o.getCertPath() != null || o.getCertValue() != null || o.getKeystore() != null;
}

When it happens

Trigger: keyCertOptions.setCertPath(null) or setCertValue(null) (or a config property resolving to null) followed by trust/cert loading via chain()/loadCA.

Common situations: Config file missing the certPath key so the property defaults to null; conditional code that skips setting the cert; environment variable not set when constructing options.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

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

Related errors

• Invalid configuration
• workerPoolSize must be > 0
• blockedThreadCheckInterval must be > 0
• maxEventLoopExecuteTime must be > 0
• maxWorkerpExecuteTime must be > 0

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