{"record":{"id":"4ba062056bb39459","repo":"quarkusio/quarkus","slug":"tls-client-authentication-is-not-available-please","errorCode":null,"errorMessage":"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'","messagePattern":"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'","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityImpl.java","lineNumber":422,"sourceCode":"                throw new IllegalArgumentException(\"Authorization has already been set\");\n            }\n        }\n\n        @Override\n        public HttpPermission basic() {\n            return authenticatedWith(BasicAuthentication.AUTH_MECHANISM_SCHEME);\n        }\n\n        @Override\n        public HttpPermission form() {\n            return authenticatedWith(FormAuthentication.AUTH_MECHANISM_SCHEME);\n        }\n\n        @Override\n        public HttpPermission mTLS() {\n            boolean mTlsDisabled = ClientAuth.NONE.equals(clientAuth);\n            if (mTlsDisabled) {\n                throw new IllegalStateException(\n                        \"TLS client authentication is not available, please enable it with this API or set the \"\n                                + \"'quarkus.http.ssl.client-auth' configuration property to 'required' or 'request'\");\n            }\n            return authenticatedWith(MTLSAuthentication.AUTH_MECHANISM_SCHEME);\n        }\n\n        @Override\n        public HttpPermission bearer() {\n            return authenticatedWith(\"Bearer\");\n        }\n\n        @Override\n        public HttpPermission webAuthn() {\n            return authenticatedWith(\"webauthn\");\n        }\n\n        @Override\n        public HttpPermission authorizationCodeFlow() {","sourceCodeStart":404,"sourceCodeEnd":440,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityImpl.java#L404-L440","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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()."],"exampleFix":"// before\nhttpSecurity.paths(\"/secure/*\").mTLS(); // IllegalStateException\n// after: application.properties\n// quarkus.http.ssl.client-auth=required\nhttpSecurity.paths(\"/secure/*\").mTLS();","handlingStrategy":"validation","validationCode":"boolean mTlsEnabled = !\"none\".equalsIgnoreCase(config.getOptionalValue(\"quarkus.http.ssl.client-auth\", String.class).orElse(\"none\"));\nif (!mTlsEnabled) throw new IllegalStateException(\"enable quarkus.http.ssl.client-auth=required before mTLS()\");","typeGuard":null,"tryCatchPattern":"try { perm.mTLS(); } catch (IllegalStateException e) { if (!e.getMessage().startsWith(\"TLS client authentication is not available\")) throw e; /* enable client-auth and retry setup */ }","preventionTips":["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."],"tags":["quarkus","http-security","mtls","tls","configuration"],"backgroundTag":"tls-client-auth-not-enabled","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}