quarkusio/quarkus · error · IllegalArgumentException

Client authentication cannot be disabled with this API

Error message

Client authentication cannot be disabled with this API

What it means

MTLS.Builder.authentication(ClientAuth) throws IllegalArgumentException when called with ClientAuth.NONE, because this API exists to ENABLE mTLS client authentication; disabling it is not supported here (client auth is controlled by build-time config tlsClientAuth).

Source

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

            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) {
            Objects.requireNonNull(clientAuthentication);
            if (clientAuthentication == ClientAuth.NONE) {
                throw new IllegalArgumentException("Client authentication cannot be disabled with this API");
            }
            this.clientAuth = clientAuthentication;
            return this;
        }

        /**
         * Selects a certificate attribute which values are mapped to the {@link SecurityIdentity} roles.
         * This attribute will be used for mappings added with the {@link #rolesMapping(String, Set)} method.
         * The default attribute value is configured to the default
         * value of the {@link AuthRuntimeConfig#certificateRoleAttribute()} configuration property.
         *
         * @param certificateAttribute certificate attribute; see {@link AuthRuntimeConfig#certificateRoleAttribute()}
         *        for information about supported values
         * @return CertificateRolesBuilder
         */
        public Builder certificateAttribute(String certificateAttribute) {
            assertCertificateToRolesMapperNotSetYet();
            this.certificateAttribute = Objects.requireNonNull(certificateAttribute);

View on GitHub (pinned to e1c734241f)

Solutions

1. Do not call authentication() when client auth should be NONE — omit the call entirely
2. Map the disabled case to skipping the mTLS builder setup
3. Control enable/disable via VertxHttpBuildTimeConfig.tlsClientAuth config instead

Example fix

// before
builder.authentication(clientAuthFromConfig); // may be NONE
// after
if (clientAuthFromConfig != ClientAuth.NONE) {
    builder.authentication(clientAuthFromConfig);
}

if (clientAuth != null && clientAuth != ClientAuth.NONE) {
    builder.authentication(clientAuth);
}

boolean isEnableableClientAuth(ClientAuth a) { return a != null && a != ClientAuth.NONE; }

When it happens

Trigger: Calling mtlsBuilder.authentication(ClientAuth.NONE), often from a config-driven switch mapping a disabled/none value to the enum.

Common situations: Config value "none" passed straight through to the builder; attempting to toggle mTLS off at runtime; generic enum-mapping code ignoring the API restriction.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• TLS configuration name has already been configured with the
• The TLS configuration name <java-net-ssl> is reserved for pr
• The TLS configuration to register cannot be null
• TLS client authentication has already been enabled with this
• Client authentication cannot be disabled with this API

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