quarkusio/quarkus · error · IllegalArgumentException

Cannot register the TLS configuration '%s' in the TLS Config

Error message

Cannot register the TLS configuration '%s' in the TLS Configuration registry because configuration with this name has already been registered

What it means

Before registering the mTLS mechanism's initial TlsConfiguration into the TlsConfigurationRegistry, Quarkus checks whether a configuration with that name already exists. Duplicate names would make TLS resolution ambiguous, so the registration is rejected with an IllegalArgumentException naming the conflicting configuration.

Source

Thrown at extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityImpl.java:154

                // there shouldn't be a technical issue allowing that, but that's the behavior we have for other mechanisms
                // as well, so this method only allows to "enable" mTLS, never disable or change configuration provided
                // properties file
                throw new IllegalArgumentException("TLS client authentication has already been enabled with this API or"
                        + " with the 'quarkus.http.ssl.client-auth' configuration property");
            }
            var mTLS = ((MtlsAuthenticationMechanism) mechanism);
            clientAuth = mTLS.getTlsClientAuth();
            if (mTLS.getHttpServerTlsConfigName().isPresent()) {
                if (httpServerTlsConfigName.isPresent()) {
                    throw new IllegalArgumentException("Cannot configure TLS configuration name programmatically because it "
                            + " has already been configured with the 'quarkus.http.tls-configuration-name' configuration property");
                }
                httpServerTlsConfigName = mTLS.getHttpServerTlsConfigName();
                if (mTLS.getInitialTlsConfiguration() != null) {
                    TlsConfigurationRegistry tlsConfigurationRegistry = Arc.container().instance(TlsConfigurationRegistry.class)
                            .get();
                    if (tlsConfigurationRegistry.get(httpServerTlsConfigName.get()).isPresent()) {
                        throw new IllegalArgumentException(("Cannot register the TLS configuration '%s' in the TLS "
                                + "Configuration registry because configuration with this name has already"
                                + " been registered").formatted(httpServerTlsConfigName.get()));
                    }
                    tlsConfigurationRegistry.register(httpServerTlsConfigName.get(), mTLS.getInitialTlsConfiguration());
                }
            }
        }
        this.mechanisms.add(mechanism);
        return this;
    }

    @Override
    public HttpSecurity basic() {
        return mechanism(Basic.create());
    }

    @Override
    public HttpSecurity basic(String authenticationRealm) {

View on GitHub (pinned to e1c734241f)

Solutions

Choose a unique name for the TLS configuration being registered programmatically.
Check tlsConfigurationRegistry.get(name).isPresent() before registering and skip or rename on conflict.
If the existing configuration is correct, do not register a new one — reference the existing name instead.

Example fix

// before
TlsConfiguration cfg = buildTlsConfig();
mechanism(MTLS.tlsConfig("my-tls", cfg)); // throws if "my-tls" registered
// after
if (Arc.container().instance(TlsConfigurationRegistry.class).get().get("my-tls").isEmpty()) {
    mechanism(MTLS.tlsConfig("my-tls", buildTlsConfig()));
}

Defensive patterns

Strategy: validation

Validate before calling

TlsConfigurationRegistry registry = Arc.container().instance(TlsConfigurationRegistry.class).get();
if (registry.get("my-tls").isPresent()) {
    log.info("TLS config 'my-tls' already registered; skipping registration");
} else {
    registry.register("my-tls", buildTlsConfig());
}

Try / catch

try {
    httpSecurity.mechanism(mtlsMechanism);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("already" ) && e.getMessage().contains("TLS Configuration registry")) {
        log.warn("Named TLS config already registered; reusing existing entry");
    } else {
        throw e;
    }
}

Prevention

Always check registry.get(name).isPresent() before registering a named TLS config.
Use unique, app-prefixed TLS config names to avoid collisions with extensions.
Make registration idempotent for dev-mode reloads.

When it happens

Trigger: Registering an mTLS mechanism whose getInitialTlsConfiguration() is non-null and whose httpServerTlsConfigName already has an entry in the TlsConfigurationRegistry (e.g. registered earlier in code or by another extension).

Common situations: Re-running security setup code that registers the same named TLS config twice; two different mechanisms trying to register TLS configurations under the same name; dev-mode hot reload re-executing registration without clearing the registry.

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