quarkusio/quarkus · error · IllegalArgumentException

TLS configuration name has already been configured with the

Error message

TLS configuration name has already been configured with the 'tls' method

What it means

MTLS.Builder.tls(String, TlsConfiguration) throws IllegalArgumentException when the TLS configuration name was already configured via the single-argument tls(String) method. The two tls(...) overloads are mutually exclusive: one sets a named config, the other an explicit TlsConfiguration with a name.

Source

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

        /**
         * Registers a TLS configuration into the registry and configures the TLS configuration used by the HTTP server
         * for the TLS communication. Please note that this method is mutually exclusive with
         * the 'quarkus.http.tls-configuration-name' configuration property and if the configuration with this name
         * is already registered in the TLS registry, validation will fail.
         * <p>
         * The passed TLS configuration is not validated, so it's up to the caller to ensure the configuration is correct.
         *
         * @param tlsConfigurationName the name of the configuration, cannot be {@code null}, cannot be {@code <default>}
         * @param tlsConfiguration the configuration cannot be {@code null}
         * @return Builder
         * @see io.quarkus.tls.TlsConfigurationRegistry#register(String, TlsConfiguration)
         * @see VertxHttpConfig#tlsConfigurationName()
         */
        public Builder tls(String tlsConfigurationName, TlsConfiguration tlsConfiguration) {
            Objects.requireNonNull(tlsConfiguration);
            Objects.requireNonNull(tlsConfigurationName);
            if (httpServerTlsConfigName.isPresent()) {
                throw new IllegalArgumentException("TLS configuration name has already been configured with the 'tls' method");
            }
            this.httpServerTlsConfigName = Optional.of(tlsConfigurationName);
            this.tlsConfiguration = tlsConfiguration;
            return this;
        }

        /**
         * When the mutual TLS client authentication is configured with this builder, the client authentication
         * is {@link ClientAuth#REQUIRED} for all requests by default. If you configure {@link ClientAuth#REQUEST},
         * the client authentication is accepted if presented by a client.
         * Use the {@link ClientAuth#REQUEST} option if the client authentication is only required for certain routes
         * and secure these routes with HTTP permissions or standard security annotations.
         *
         * @param clientAuthentication {@link ClientAuth#REQUEST} or {@link ClientAuth#REQUIRED}
         * @return Builder
         * @see VertxHttpBuildTimeConfig#tlsClientAuth() for more information
         */
        public Builder authentication(ClientAuth clientAuthentication) {

View on GitHub (pinned to e1c734241f)

Solutions

Use only one tls() overload per builder instance
Remove the earlier tls(name) call if the explicit TlsConfiguration variant is wanted
Split configuration into separate builders if both styles are required

Example fix

// before
builder.tls("db-tls");
builder.tls("db-tls", tlsConfig); // IllegalArgumentException
// after
builder.tls("db-tls", tlsConfig);

Defensive patterns

Strategy: validation

Validate before calling

if (explicitTlsConfig != null) {
    builder.tls(name, explicitTlsConfig);
} else {
    builder.tls(name);
}

Try / catch

try {
    builder.tls(name, tlsConfig);
} catch (IllegalArgumentException e) {
    // name already set via tls(String) — restructure to a single call
}

Prevention

Choose one TLS configuration style per builder
Let the explicit TlsConfiguration overload take precedence in shared helpers
Document which code path owns TLS setup

When it happens

Trigger: Calling tls(name, tlsConfiguration) after tls(name) was already called on the same builder.

Common situations: Mixing two TLS setup styles in one builder; a shared helper method that calls tls(name) followed by app code calling tls(name, 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/c4042cb479e7980e. Report an issue: GitHub.