quarkusio/quarkus · error · ConfigurationException

The 'quarkus.http.auth.certificate-role-properties' configur

Error message

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

What it means

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.

Source

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

                RolesMapping rolesMapping) {
            // null checks in this method are here because this is a public method
            // but class members should be initialized once, before the router is finalized
            if (this.pathMatchingPolicy == null) {
                this.pathMatchingPolicy = pathMatchingPolicy;
            }
            if (this.rolesMapping == null) {
                this.rolesMapping = rolesMapping;
            }
        }
    }

    public void setMtlsCertificateRoleProperties() {
        MtlsAuthenticationMechanism mTLS = HttpSecurityConfiguration.get().getMtlsAuthenticationMechanism();
        if (mTLS != null) {
            VertxHttpConfig httpConfig = this.httpConfig.getValue();
            if (httpConfig.auth().certificateRoleProperties().isPresent()) {
                if (mTLS.isCertificateToRolesMapperSet()) {
                    throw new ConfigurationException("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".formatted(MTLS.class.getName()),
                            Set.of("quarkus.http.auth.certificate-role-properties"));
                }
                Path rolesPath = httpConfig.auth().certificateRoleProperties().get();
                URL rolesResource = null;
                if (Files.exists(rolesPath)) {
                    try {
                        rolesResource = rolesPath.toUri().toURL();
                    } catch (MalformedURLException e) {
                        // The Files.exists(rolesPath) check has succeeded therefore this exception can't happen in this case
                    }
                } else {
                    rolesResource = Thread.currentThread().getContextClassLoader().getResource(rolesPath.toString());
                }
                if (rolesResource == null) {
                    throw new ConfigurationException(
                            "quarkus.http.auth.certificate-role-properties location can not be resolved",

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove the quarkus.http.auth.certificate-role-properties property if you configure roles via the programmatic MTLS API.
2. Alternatively remove the programmatic setCertificateRolePaths/mapper call and keep only the config property.
3. Pick one source of truth for certificate-to-role mapping across all profiles/environments.

Example fix

// before: application.properties
// quarkus.http.auth.certificate-role-properties=cert-roles.properties
mtlsApi.certificateToRoles(...); // ConfigurationException
// after: delete the property line, keep programmatic API (or vice versa)

boolean propSet = config.getOptionalValue("quarkus.http.auth.certificate-role-properties", String.class).isPresent();
boolean apiSet = /* programmatic mapper registered */ false;
if (propSet && apiSet) throw new IllegalStateException("choose either config property or programmatic MTLS role mapping");

try { /* build */ } catch (ConfigurationException e) { if (!e.getMessage().contains("certificate-role-properties")) throw e; /* remove one of the two config sources */ }

When it happens

Trigger: Calling the MTLS certificate-role mapper API (MTLS.class programmatic setup) while application.properties still contains quarkus.http.auth.certificate-role-properties.

Common situations: 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.

Understand the failure class

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

Related errors

• quarkus.http.auth.certificate-role-properties location can n
• Invalid proxy passed to recorder. ${rp} was created in a run
• Quarkus manual bootstrap failed
• Command line arguments not available during static init
• Persistence providers are not available during the static in

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