eclipse-vertx/vert.x · error · VertxException

PQC enforcement policy ${pqcPolicy} requires PQ compliant na

Error message

PQC enforcement policy ${pqcPolicy} requires PQ compliant named groups but the configured SSL engine does not support it

What it means

SslContextManager.resolveEngineOptions throws VertxException when a PQC enforcement policy is configured but the explicitly chosen SSL engine (JDK or OpenSSL as set by the user) does not expose PQ-compliant named groups (e.g. ML-KEM hybrids). Vert.x refuses to run with a policy it cannot satisfy.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/internal/tls/SslContextManager.java:99

  /**
   * Resolve the ssl engine options to use for properly running the configured options,
   * taking PQC enforcement policy into account.
   */
  public static SSLEngineOptions resolveEngineOptions(SSLEngineOptions engineOptions, boolean useAlpn, PqcEnforcementPolicy pqcPolicy) {
    if (pqcPolicy == null) {
      pqcPolicy = PqcEnforcementPolicy.RELAXED;
    }
    if (pqcPolicy == PqcEnforcementPolicy.STRICT || pqcPolicy == PqcEnforcementPolicy.CLIENT_NEGOTIATED) {
      if (engineOptions != null) {
        // we check that the user provided a PQ compliant SSL Engine
        boolean pqcSupported;
        if (engineOptions instanceof JdkSSLEngineOptions) {
          pqcSupported = JdkSSLEngineOptions.isPqcAvailable();
        } else {
          pqcSupported = OpenSSLEngineOptions.isPqcAvailable();
        }
        if (!pqcSupported) {
          throw new VertxException("PQC enforcement policy " + pqcPolicy + " requires PQ compliant named groups but the configured SSL engine does not support it");
        }
      } else {
        // the user didn't specify any SSL engine, we pick one for them
        if (JdkSSLEngineOptions.isPqcAvailable()) {
          log.debug("JdkSslEngine supports PQ compliant groups, it will be used for the application");
          engineOptions = new JdkSSLEngineOptions();
        } else if (OpenSSLEngineOptions.isPqcAvailable()) {
          log.debug("OpenSslEngine supports PQ compliant groups, it will be used for the application");
          engineOptions = new OpenSSLEngineOptions();
        } else {
          throw new VertxException("PQC enforcement policy " + pqcPolicy + " requires PQ compliant named groups but neither JDK nor OpenSSL support it");
        }
      }
    }
    if (engineOptions == null) {
      if (useAlpn) {
        if (JdkSSLEngineOptions.isAlpnAvailable()) {
          engineOptions = new JdkSSLEngineOptions();

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Upgrade to a JDK/OpenSSL that supports PQ named groups (e.g. JDK 24+, OpenSSL 3.5+ with ML-KEM).
2. Remove the explicit sslEngineOptions so Vert.x auto-selects a PQ-capable engine.
3. Lower/relax the PQC enforcement policy if PQ groups are not actually required.
4. For OpenSSL, use a netty-tcnative BoringSSL build with PQ groups enabled.

Example fix

// before
options.setSslEngineOptions(new JdkSSLEngineOptions()); // JDK without PQ
// after
// omit engine options: Vert.x picks a PQ-capable engine
options.setPqcPolicy(PqcPolicy.ENFORCE);

if (!JdkSSLEngineOptions.isPqcAvailable() && !OpenSSLEngineOptions.isPqcAvailable()) {
  throw new IllegalStateException("Runtime does not support PQ named groups; do not force an engine with PQC policy");
}

try { engineOpts = manager.resolveEngineOptions(...); } catch (VertxException e) { /* fall back to non-enforced policy or abort with clear message */ }

When it happens

Trigger: Setting sslEngineOptions to JdkSSLEngineOptions or OpenSSLEngineOptions while requiring a PQC enforcement policy, and JdkSSLEngineOptions.isPqcAvailable()/OpenSSLEngineOptions.isPqcAvailable() returns false (old JDK or OpenSSL without PQ groups).

Common situations: Running on JDK < 24 (or without hybrid X25519MLKEM768 groups) or a netty-tcnative build without PQ support while a security policy mandates post-quantum key exchange.

Understand the failure class

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

Related errors

• PQC enforcement policy ${pqcPolicy} requires PQ compliant na
• Not listening
• KeyManagerFactory is not present or is not initialized yet
• Invalid configuration
• SSL configuration is necessary for a QUIC server

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