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 of override it

What it means

Quarkus's TLS registry reserves the configuration name '<java-net-ssl>' for the built-in configuration that exposes the default SunJSSE keystore (the JVM-wide default used by java.net clients). Registering a custom TlsConfiguration under this name would silently override JVM default SSL behavior, so CertificateRecorder.register throws IllegalArgumentException to prevent it.

Source

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

        }
        return Optional.ofNullable(certificates.get(name));
    }

    @Override
    public Optional<TlsConfiguration> getDefault() {
        return get(TlsConfig.DEFAULT_NAME);
    }

    @Override
    public void register(String name, TlsConfiguration configuration) {
        if (name == null) {
            throw new IllegalArgumentException("The name of the TLS configuration to register cannot be null");
        }
        if (name.equals(TlsConfig.DEFAULT_NAME)) {
            throw new IllegalArgumentException("The name of the TLS configuration to register cannot be <default>");
        }
        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 of override it");
        }
        if (configuration == null) {
            throw new IllegalArgumentException("The TLS configuration to register cannot be null");
        }
        certificates.put(name, configuration);
    }

    public Supplier<TlsConfigurationRegistry> getSupplier() {
        return new Supplier<TlsConfigurationRegistry>() {
            @Override
            public TlsConfigurationRegistry get() {
                return CertificateRecorder.this;
            }
        };
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Rename your TLS configuration to something other than '<java-net-ssl>' (e.g. 'my-app-ssl') and reference that name from your client/server config (tls.configuration-name / tls.*-tls-configuration-name).
2. To customize the JVM default, configure the JDK keystore via -Djavax.net.ssl.keyStore/-Djavax.net.ssl.trustStore or quarkus.tls.key-store/-trust-store default settings instead of registering '<java-net-ssl>'.
3. If you need to access the SunJSSE default configuration, look it up via the registry rather than trying to register/replace it.

Example fix

// before
registry.register("<java-net-ssl>", myConfig);
// after
registry.register("my-app-ssl", myConfig);

if (TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME.equals(name)) {
    throw new IllegalArgumentException("'<java-net-ssl>' is reserved; choose a custom name");
}
TlsConfigurationRegistry registry = ...;
if (registry.get(name) != null) { /* decide whether overwrite is intended */ }

boolean isReservedName(String name) {
    return TlsConfig.DEFAULT_NAME.equals(name) || TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME.equals(name);
}

try {
    recorder.register(name, config);
} catch (IllegalArgumentException e) {
    log.errorf("Cannot register TLS config '%s': %s", name, e.getMessage());
}

When it happens

Trigger: Calling TlsConfigurationRegistry/Building register(name, configuration) (directly or via a custom extension recorder) with name equal to TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME, i.e. '<java-net-ssl>'.

Common situations: Writing a custom extension that contributes a TLS configuration and using a constant or user-supplied name that resolves to '<java-net-ssl>'; copying sample code that registers the java-net-ssl configuration; end users trying to override the default JVM keystore through the registry.

Understand the failure class

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

Related errors

• The name of the TLS configuration to register cannot be <def
• The TLS configuration to register cannot be null
• TLS configuration name has already been configured with the
• Client authentication cannot be disabled with this API
• Name cannot start with '/':${name}

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