quarkusio/quarkus · error · IllegalArgumentException

Cannot configure TLS configuration name programmatically bec

Error message

Cannot configure TLS configuration name programmatically because it  has already been configured with the 'quarkus.http.tls-configuration-name' configuration property

What it means

When an MtlsAuthenticationMechanism carries a named TLS configuration (set via quarkus.tls.<name>.* on the mechanism), Quarkus stores it as httpServerTlsConfigName. If a TLS configuration name was already provided — either through the quarkus.http.tls-configuration-name property or a previous programmatic registration — the second assignment throws an IllegalArgumentException because two named TLS configs cannot be reconciled.

Source

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

            if (actualRealm != null) {
                throw new IllegalArgumentException("Cannot configure basic authentication programmatically because "
                        + "the authentication realm has already been configured in the 'application.properties' file");
            }
        } else if (mechanism.getClass() == MtlsAuthenticationMechanism.class) {
            boolean mTlsEnabled = !ClientAuth.NONE.equals(clientAuth);
            if (mTlsEnabled) {
                // current we do not allow "merging" (or overriding) of the configuration provided in application.properties
                // 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;
    }

View on GitHub (pinned to e1c734241f)

Solutions

Remove quarkus.http.tls-configuration-name from application.properties so the programmatic TLS config name is the only one.
Set the TLS configuration name in only one place — either the mechanism or the property, not both.
If multiple TLS configs are needed, register them in the TlsConfigurationRegistry under distinct names and reference them consistently.

Example fix

// before (application.properties)
quarkus.http.tls-configuration-name=server-tls
// code: mechanism(MTLS.named("server-tls")) // throws
// after: remove the property, then configure the name only via the mechanism

Defensive patterns

Strategy: validation

Validate before calling

// ensure quarkus.http.tls-configuration-name is unset before naming a TLS config programmatically
// ConfigProvider.getConfig().getOptionalValue("quarkus.http.tls-configuration-name", String.class)
//     .ifPresent(n -> { throw new IllegalStateException("TLS config name already set in properties"); });

Try / catch

try {
    httpSecurity.mechanism(mtlsMechanism);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("TLS configuration name")) {
        log.warn("quarkus.http.tls-configuration-name already set; properties value will be used");
    } else {
        throw e;
    }
}

Prevention

Set the HTTP TLS configuration name in exactly one place: property or mechanism.
Name distinct TLS configurations uniquely in the TLS registry.
When migrating to the TLS registry, delete the old quarkus.http.tls-configuration-name entry.

When it happens

Trigger: Registering an mTLS mechanism with getHttpServerTlsConfigName() present while application.properties sets quarkus.http.tls-configuration-name, or while an earlier mechanism() call already set httpServerTlsConfigName.

Common situations: Apps switching to the TLS registry naming scheme while quarkus.http.tls-configuration-name remains defined; registering two mTLS mechanisms each with their own named TLS config.

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