{"record":{"id":"bbc1297c11c97719","repo":"quarkusio/quarkus","slug":"the-quarkus-http-auth-certificate-role-properties","errorCode":null,"errorMessage":"The 'quarkus.http.auth.certificate-role-properties' configuration property is set, but the certificate to roles mapping has been configured programmatically with the '%s' API","messagePattern":"The 'quarkus\\.http\\.auth\\.certificate-role-properties' configuration property is set, but the certificate to roles mapping has been configured programmatically with the '(.+?)' API","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityRecorder.java","lineNumber":478,"sourceCode":"                RolesMapping rolesMapping) {\n            // null checks in this method are here because this is a public method\n            // but class members should be initialized once, before the router is finalized\n            if (this.pathMatchingPolicy == null) {\n                this.pathMatchingPolicy = pathMatchingPolicy;\n            }\n            if (this.rolesMapping == null) {\n                this.rolesMapping = rolesMapping;\n            }\n        }\n    }\n\n    public void setMtlsCertificateRoleProperties() {\n        MtlsAuthenticationMechanism mTLS = HttpSecurityConfiguration.get().getMtlsAuthenticationMechanism();\n        if (mTLS != null) {\n            VertxHttpConfig httpConfig = this.httpConfig.getValue();\n            if (httpConfig.auth().certificateRoleProperties().isPresent()) {\n                if (mTLS.isCertificateToRolesMapperSet()) {\n                    throw new ConfigurationException(\"The 'quarkus.http.auth.certificate-role-properties' configuration\"\n                            + \" property is set, but the certificate to roles mapping has been configured \"\n                            + \"programmatically with the '%s' API\".formatted(MTLS.class.getName()),\n                            Set.of(\"quarkus.http.auth.certificate-role-properties\"));\n                }\n                Path rolesPath = httpConfig.auth().certificateRoleProperties().get();\n                URL rolesResource = null;\n                if (Files.exists(rolesPath)) {\n                    try {\n                        rolesResource = rolesPath.toUri().toURL();\n                    } catch (MalformedURLException e) {\n                        // The Files.exists(rolesPath) check has succeeded therefore this exception can't happen in this case\n                    }\n                } else {\n                    rolesResource = Thread.currentThread().getContextClassLoader().getResource(rolesPath.toString());\n                }\n                if (rolesResource == null) {\n                    throw new ConfigurationException(\n                            \"quarkus.http.auth.certificate-role-properties location can not be resolved\",","sourceCodeStart":460,"sourceCodeEnd":496,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityRecorder.java#L460-L496","documentation":"Thrown by HttpSecurityRecorder.setMtlsCertificateRoleProperties as a ConfigurationException during static init/recording when both the 'quarkus.http.auth.certificate-role-properties' config property is present AND the certificate-to-roles mapping was already set programmatically via the MTLS API. The two configuration channels are mutually exclusive, so Quarkus aborts rather than silently choosing one.","triggerScenarios":"Calling the MTLS certificate-role mapper API (MTLS.class programmatic setup) while application.properties still contains quarkus.http.auth.certificate-role-properties.","commonSituations":"Migrating from properties-file mTLS role mapping to programmatic configuration (or vice versa) and leaving both in place; shared config files inherited by a codebase that moved to the API.","solutions":["Remove the quarkus.http.auth.certificate-role-properties property if you configure roles via the programmatic MTLS API.","Alternatively remove the programmatic setCertificateRolePaths/mapper call and keep only the config property.","Pick one source of truth for certificate-to-role mapping across all profiles/environments."],"exampleFix":"// before: application.properties\n// quarkus.http.auth.certificate-role-properties=cert-roles.properties\nmtlsApi.certificateToRoles(...); // ConfigurationException\n// after: delete the property line, keep programmatic API (or vice versa)","handlingStrategy":"validation","validationCode":"boolean propSet = config.getOptionalValue(\"quarkus.http.auth.certificate-role-properties\", String.class).isPresent();\nboolean apiSet = /* programmatic mapper registered */ false;\nif (propSet && apiSet) throw new IllegalStateException(\"choose either config property or programmatic MTLS role mapping\");","typeGuard":null,"tryCatchPattern":"try { /* build */ } catch (ConfigurationException e) { if (!e.getMessage().contains(\"certificate-role-properties\")) throw e; /* remove one of the two config sources */ }","preventionTips":["Keep a single source of truth for mTLS role mapping.","Grep application properties for certificate-role-properties when adopting the programmatic API.","Check all profiles (%,test, ,prod) for leftover properties."],"tags":["quarkus","mtls","configuration-conflict","static-init"],"backgroundTag":"duplicate-configuration-source","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}