quarkusio/quarkus · error · IllegalArgumentException

The name of the TLS configuration to register cannot be <def

Error message

The name of the TLS configuration to register cannot be <default>

What it means

register(name, configuration) cannot register a configuration under the reserved name <default>; the default TLS configuration is managed internally by the TLS registry. Attempting to replace it programmatically is rejected with IllegalArgumentException to keep the default configuration authoritative.

Source

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

                return new VertxCertificateHolder(vertx, k, runtimeConfig.getValue().namedCertificateConfig().get(k), null, ts);
            });
            return Optional.ofNullable(result);
        }
        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. Register under a custom name (e.g. "my-tls") and reference that name where the configuration is consumed
2. To influence the default configuration, use the unnamed quarkus.tls.* config properties instead of programmatic registration
3. Filter out TlsConfig.DEFAULT_NAME before looping over configuration buckets to register

Example fix

// before
registry.register("<default>", configuration);
// after
registry.register("my-tls", configuration);

if (TlsConfig.DEFAULT_NAME.equals(name)) {
    throw new IllegalArgumentException("Use unnamed quarkus.tls.* config to change the default TLS configuration");
}

static boolean isRegisterableTlsName(String name) {
    return name != null && !TlsConfig.DEFAULT_NAME.equals(name)
        && !TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME.equals(name);
}

try {
    registry.register(name, configuration);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("cannot be <default>")) {
        log.error("Register under a custom name; the default TLS config is managed by Quarkus", e);
    } else { throw e; }
}

When it happens

Trigger: Application or extension code calls tlsConfigurationRegistry.register("<default>", configuration) or passes a name variable that evaluates to TlsConfig.DEFAULT_NAME.

Common situations: Trying to override the default TLS configuration at runtime; generic registration loops over config buckets that accidentally include the <default> key; copying registry names into re-registration calls.

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 null
• The TLS configuration name <java-net-ssl> is reserved for pr
• A generic type is not allowed here; try creating a subclass
• Build item class must be leaf (final) types: %s
• Cannot construct empty build items

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