quarkusio/quarkus · error · IllegalStateException

TLS client authentication is not available, please enable it

Error message

TLS client authentication is not available, please enable it with this API or set the 'quarkus.http.ssl.client-auth' configuration property to 'required' or 'request'

What it means

Thrown by HttpPermission.mTLS() when mTLS client authentication is disabled (quarkus.http.ssl.client-auth is NONE, the default). Requesting mTLS authentication is pointless unless the server actually asks for client certificates, so Quarkus fails at build/startup time with IllegalStateException instead of silently ignoring the rule.

Source

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

                throw new IllegalArgumentException("Authorization has already been set");
            }
        }

        @Override
        public HttpPermission basic() {
            return authenticatedWith(BasicAuthentication.AUTH_MECHANISM_SCHEME);
        }

        @Override
        public HttpPermission form() {
            return authenticatedWith(FormAuthentication.AUTH_MECHANISM_SCHEME);
        }

        @Override
        public HttpPermission mTLS() {
            boolean mTlsDisabled = ClientAuth.NONE.equals(clientAuth);
            if (mTlsDisabled) {
                throw new IllegalStateException(
                        "TLS client authentication is not available, please enable it with this API or set the "
                                + "'quarkus.http.ssl.client-auth' configuration property to 'required' or 'request'");
            }
            return authenticatedWith(MTLSAuthentication.AUTH_MECHANISM_SCHEME);
        }

        @Override
        public HttpPermission bearer() {
            return authenticatedWith("Bearer");
        }

        @Override
        public HttpPermission webAuthn() {
            return authenticatedWith("webauthn");
        }

        @Override
        public HttpPermission authorizationCodeFlow() {

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.http.ssl.client-auth=required (or request) in application.properties.
Enable TLS client authentication programmatically via the Vert.x HTTP configuration API before using mTLS().
If TLS is terminated at a proxy, pass the client certificate through (e.g. proxy forwarding headers + custom mechanism) instead of mTLS().

Example fix

// before
httpSecurity.paths("/secure/*").mTLS(); // IllegalStateException
// after: application.properties
// quarkus.http.ssl.client-auth=required
httpSecurity.paths("/secure/*").mTLS();

Defensive patterns

Strategy: validation

Validate before calling

boolean mTlsEnabled = !"none".equalsIgnoreCase(config.getOptionalValue("quarkus.http.ssl.client-auth", String.class).orElse("none"));
if (!mTlsEnabled) throw new IllegalStateException("enable quarkus.http.ssl.client-auth=required before mTLS()");

Try / catch

try { perm.mTLS(); } catch (IllegalStateException e) { if (!e.getMessage().startsWith("TLS client authentication is not available")) throw e; /* enable client-auth and retry setup */ }

Prevention

Always pair mTLS() with quarkus.http.ssl.client-auth=required or request.
Verify your TLS termination topology (proxy vs Quarkus) before using mTLS().
Add a startup check asserting client-auth config matches security rules.

When it happens

Trigger: Calling httpSecurity.paths(...).mTLS() without quarkus.http.ssl.client-auth=required (or request) in configuration and without enabling client auth programmatically via the VertxHttpRecorder/HTTP build API.

Common situations: Deploying behind a proxy that terminates TLS so client certs never reach Quarkus; forgetting the ssl.client-auth property while adding an mTLS path rule; moving an app from a manually configured TLS setup to the new HttpSecurity API.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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