quarkusio/quarkus · error · IllegalArgumentException

The TLS configuration name <default> cannot be used explicit

Error message

The TLS configuration name <default> cannot be used explicitly in configuration or qualifiers

What it means

The TLS registry reserves the name <default> for the implicitly-registered default TLS configuration. At startup, CertificateRecorder.validateCertificates() scans all named quarkus.tls.key-store.*-style certificate configs and fails fast if any is explicitly named <default>, because named configurations must use a distinct name while the default is reached by omitting the name. This is a configuration validation error thrown as IllegalArgumentException during static init/startup.

Source

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

     * @param vertx the Vert.x instance
     */
    public void validateCertificates(Set<String> providerBucketNames,
            RuntimeValue<Vertx> vertx,
            ShutdownContext shutdownContext) {
        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();
                }
            }

View on GitHub (pinned to e1c734241f)

Solutions

Remove the <default> named block and configure the default TLS configuration with unnamed properties (quarkus.tls.key-store.*) instead
Rename the configuration to a custom name (e.g. my-tls) and reference it via the matching qualifier/config name
Check property keys, including env-var forms like QUARKUS_TLS_KEY_STORE____DEFAULT__, for the literal <default> name

Example fix

// before (application.properties)
quarkus.tls.key-store."<default>".paths=tls/server.pem
// after
quarkus.tls.key-store.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("<default>"))) {
    throw new IllegalStateException("TLS config must not be named <default>; use unnamed quarkus.tls.* properties");
}

Try / catch

try {
    // application startup / config registration
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("cannot be used explicitly")) {
        log.error("Fix TLS config naming: remove the <default> named block", e);
    } else { throw e; }
}

Prevention

Configure the default TLS config with unnamed quarkus.tls.key-store.*/trust-store.* properties
Never quote <default> or <java-net-ssl> as a named bucket key
Grep application.properties/yaml and env vars for the literal string <default> before startup

When it happens

Trigger: A quarkus.tls.key-store."<default>".* or quarkus.tls.trust-store."<default>".* property block is set in application.properties/yaml, an environment variable expands to the <default> key, or a TlsConfig/qualifier references the default name explicitly.

Common situations: Copy-pasting an example named TLS config block and leaving the name as <default>; renaming an existing named config to <default> hoping to override the default config; YAML/properties quoting confusion where the bucket key literally becomes <default>.

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/75cd9602d25a0532. Report an issue: GitHub.