quarkusio/quarkus · error · ConfigurationException

quarkus.http.auth.certificate-role-properties location can n

Error message

quarkus.http.auth.certificate-role-properties location can not be resolved

What it means

Thrown by HttpSecurityRecorder.setMtlsCertificateRoleProperties as a ConfigurationException when the location given by 'quarkus.http.auth.certificate-role-properties' cannot be resolved: it is neither an existing filesystem path nor a classpath resource reachable via the context class loader. The rolesResource ends up null and startup fails.

Source

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

                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",
                            Set.of("quarkus.http.auth.certificate-role-properties"));
                }

                try (Reader reader = new BufferedReader(
                        new InputStreamReader(rolesResource.openStream(), StandardCharsets.UTF_8))) {
                    Properties rolesProps = new Properties();
                    rolesProps.load(reader);

                    Map<String, Set<String>> roles = new HashMap<>();
                    for (Map.Entry<Object, Object> e : rolesProps.entrySet()) {
                        log.debugf("Added role mapping for %s:%s", e.getKey(), e.getValue());
                        roles.put((String) e.getKey(), parseRoles((String) e.getValue()));
                    }

                    if (!roles.isEmpty()) {
                        var certRolesAttribute = new CertificateRoleAttribute(httpConfig.auth().certificateRoleAttribute(),
                                roles);

View on GitHub (pinned to e1c734241f)

Solutions

1. Put the properties file in src/main/resources so it ships on the classpath and reference it by resource name.
2. Fix the configured path (absolute path, correct mount in the container) so Files.exists() succeeds.
3. For native builds, ensure the file is included as a resource (quarkus.native.resources.includes) rather than relying on filesystem paths.

Example fix

// before
// quarkus.http.auth.certificate-role-properties=/local/cert-roles.properties  (not in image)
// after: move file to src/main/resources/cert-roles.properties
// quarkus.http.auth.certificate-role-properties=cert-roles.properties

String loc = config.getValue("quarkus.http.auth.certificate-role-properties");
if (loc != null && !Files.exists(Path.of(loc)) && Thread.currentThread().getContextClassLoader().getResource(loc) == null) {
    throw new IllegalStateException("certificate-role-properties location not resolvable: " + loc);
}

try { /* build */ } catch (ConfigurationException e) { if (!e.getMessage().contains("location can not be resolved")) throw e; /* fix or remove the property */ }

When it happens

Trigger: Setting quarkus.http.auth.certificate-role-properties to a file path that does not exist on disk and is not on the classpath, e.g. a path valid only on the developer machine, a file excluded from the native image, or a typo'd resource name.

Common situations: Native-image builds where the properties file was not included as a resource; container images missing the mounted file; relative paths resolved against the wrong working directory; resources placed outside src/main/resources.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

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

Related errors

• TLS client authentication is not available, please enable it
• The 'quarkus.http.auth.certificate-role-properties' configur
• Failed to load application configuration
• Failed to initialize application configuration
• Unrecognized option for quarkus.bootstrap.misaligned-platfor

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