quarkusio/quarkus · error · IllegalStateException

TLS configuration is already set

Error message

TLS configuration is already set

What it means

MTLS.Builder.tls(String) throws IllegalStateException when a TLS configuration was already set on this builder. The builder allows only one TLS configuration source, so calling tls(name) after a previous tls(...) call conflicts.

Source

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

            this.clientAuth = ClientAuth.REQUIRED;
            this.certificateAttributeValueToRoles = null;
            this.httpServerTlsConfigName = Optional.empty();
            this.tlsConfiguration = null;
            this.priority = Optional.empty();
        }

        /**
         * Configures the name of 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.
         *
         * @param tlsConfigurationName the name of the configuration, cannot be {@code <default>}
         * @return Builder
         * @see VertxHttpConfig#tlsConfigurationName() for more information
         */
        public Builder tls(String tlsConfigurationName) {
            if (tlsConfiguration != null) {
                throw new IllegalStateException("TLS configuration is already set");
            }
            this.httpServerTlsConfigName = Optional.ofNullable(tlsConfigurationName);
            return this;
        }

        /**
         * 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()

View on GitHub (pinned to e1c734241f)

Solutions

1. Call tls() only once per builder
2. Remove the redundant tls() call or restructure so only one path sets TLS
3. Create a fresh MTLS.Builder if a different TLS config is needed

Example fix

// before
builder.tls("default-tls");
if (custom) {
    builder.tls("custom-tls"); // IllegalStateException
}
// after
builder.tls(custom ? "custom-tls" : "default-tls");

// ensure tls() is invoked at most once per builder
boolean tlsSet = false;
void setTls(MTLS.Builder b, String name) {
    if (tlsSet) throw new IllegalStateException("tls already configured");
    b.tls(name);
    tlsSet = true;
}

try {
    builder.tls(name);
} catch (IllegalStateException e) {
    // TLS already set — keep existing configuration or use a new builder
}

When it happens

Trigger: Calling tls(tlsConfigurationName) twice, or calling tls(name) after tls(name, tlsConfiguration) was already invoked.

Common situations: Copy-pasted builder setup where TLS is configured both conditionally and unconditionally; merging default and custom TLS setup code paths; both application.properties TLS config and programmatic config applied.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• TLS configuration name has already been configured with the
• TLS client authentication has already been enabled with this
• Client authentication cannot be disabled with this API
• TLS client authentication is not available, please enable it
• Client authentication cannot be disabled with this API

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