quarkusio/quarkus · error · IllegalArgumentException

The TLS configuration name <java-net-ssl> is reserved for pr

Error message

The TLS configuration name <java-net-ssl> is reserved for providing access to default SunJSSE keystore; neither Quarkus extensions nor end users can adjust or override it

What it means

The name <java-net-ssl> is reserved by the TLS registry for the built-in configuration exposing the default SunJSSE (java.net.ssl) keystore. validateCertificates() rejects any user- or extension-supplied named certificate config with this name so the reserved configuration can never be adjusted or overridden. Thrown as IllegalArgumentException during startup validation.

Source

Thrown at extensions/tls-registry/runtime/src/main/java/io/quarkus/tls/runtime/CertificateRecorder.java:83

        this.vertx = vertx.getValue();
        // Verify the default config
        if (runtimeConfig.getValue().defaultCertificateConfig().isPresent()) {
            verifyCertificateConfig(runtimeConfig.getValue().defaultCertificateConfig().get(), vertx.getValue(),
                    TlsConfig.DEFAULT_NAME);
        }

        var bucketNames = new HashSet<>(runtimeConfig.getValue().namedCertificateConfig().keySet());
        bucketNames.addAll(providerBucketNames);

        // Verify the named configs
        for (String name : bucketNames) {
            if (name.equals(TlsConfig.DEFAULT_NAME)) {
                throw new IllegalArgumentException(
                        "The TLS configuration name " + TlsConfig.DEFAULT_NAME
                                + " cannot be used explicitly in configuration or qualifiers");
            }
            if (name.equals(TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME)) {
                throw new IllegalArgumentException(
                        "The TLS configuration name " + TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME
                                + " is reserved for providing access to default SunJSSE keystore; neither Quarkus extensions nor end users can adjust or override it");
            }
            verifyCertificateConfig(runtimeConfig.getValue().namedCertificateConfig().get(name), vertx.getValue(), name);
        }

        shutdownContext.addShutdownTask(new Runnable() {
            @Override
            public void run() {
                if (reloader != null) {
                    reloader.close();
                }
            }
        });
    }

    private void verifyCertificateConfig(TlsBucketConfig config, Vertx vertx, String name) {
        final TlsConfiguration tlsConfig = verifyCertificateConfigInternal(config, vertx, name);

View on GitHub (pinned to e1c734241f)

Solutions

Rename the configuration block to a custom name (e.g. quarkus.tls.key-store."jdk-tls".*)
If the goal is to tune the JDK default SSLContext, configure it via standard JSSE system properties instead of the TLS registry
Use unnamed quarkus.tls.* properties if the intent was to change the default Quarkus configuration

Example fix

// before
quarkus.tls.key-store."<java-net-ssl>".paths=tls/server.pem
// after
quarkus.tls.key-store."jdk-tls".paths=tls/server.pem

Defensive patterns

Strategy: validation

Validate before calling

Set<String> names = ConfigProvider.getConfig().getPropertyNames();
if (names.stream().anyMatch(p -> p.startsWith("quarkus.tls.") && p.contains("<java-net-ssl>"))) {
    throw new IllegalStateException("<java-net-ssl> is reserved; use a custom TLS config name");
}

Try / catch

try {
    // application startup / config registration
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("reserved")) {
        log.error("Rename the TLS config; <java-net-ssl> cannot be overridden", e);
    } else { throw e; }
}

Prevention

Treat <default> and <java-net-ssl> as reserved names in all TLS config keys
Tune the JDK default keystore via JSSE system properties, not the TLS registry
Add a startup config check that rejects reserved bucket names

When it happens

Trigger: Defining quarkus.tls.key-store."<java-net-ssl>".* (or trust-store) in configuration, or an extension registering a named TLS config bucket named <java-net-ssl>.

Common situations: Trying to customize the JDK default keystore through the TLS registry naming scheme; a typo or macro expansion producing the reserved key; migrating configs from older Quarkus where the name was not reserved.

Understand the failure class

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

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/960e13a4db600119. Report an issue: GitHub.