quarkusio/quarkus · error · IllegalStateException

capabilityErrors.report()

Error message

capabilityErrors.report()

What it means

Quarkus aggregates the capabilities each extension provides and requires during the build. If one or more requested capabilities could not be satisfied by any extension on the classpath, CapabilityErrors accumulates them and this step throws an IllegalStateException with the formatted report, aborting the build.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/steps/CapabilityAggregationStep.java:158

        if (!capsProvidedByBuildSteps.isEmpty()) {
            final StringWriter buf = new StringWriter();
            try (BufferedWriter writer = new BufferedWriter(buf)) {
                writer.append("The following capabilities were found to be missing from the processed extension descriptors:");
                for (Map.Entry<String, List<String>> provider : capsProvidedByBuildSteps.entrySet()) {
                    for (String capability : provider.getValue()) {
                        writer.newLine();
                        writer.append(" - " + capability + " provided by ").append(provider.getKey());
                    }
                }
                writer.newLine();
                writer.append("Please report this issue to the extension maintainers to get it fixed in the future releases.");
            } catch (IOException e) {
            }
            Logger.getLogger(CapabilityAggregationStep.class).warn(buf.toString());
        }

        if (capabilityErrors != null && !capabilityErrors.isEmpty()) {
            throw new IllegalStateException(capabilityErrors.report());
        }

        return new Capabilities(providedCapabilities.keySet());
    }

    private static CapabilityErrors createIfNull(CapabilityErrors capabilityErrors) {
        return capabilityErrors == null ? capabilityErrors = new CapabilityErrors() : capabilityErrors;
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the extension that provides the missing capability named in the report (e.g. quarkus-agroal for io.quarkus.jdbc capability)
2. Re-enable the excluded extension whose capability is required (set quarkus.<ext>.enabled=true or remove the exclusion)
3. Check the full report — it lists each missing capability and usually the requesting extension — and align extension versions in the BOM
4. If a custom extension requests a capability, register a CapabilityBuildItem provider or remove the requirement

Example fix

// before (pom.xml: extension needs a datasource but none is present)
<dependency>io.quarkus:quarkus-hibernate-orm</dependency>
// after
<dependency>io.quarkus:quarkus-hibernate-orm</dependency>
<dependency>io.quarkus:quarkus-jdbc-postgresql</dependency>

List<String> required = List.of("io.quarkus.jdbc.postgresql", "io.quarkus.hibernate.orm");
for (String dep : required) {
    if (!projectDependenciesContain(dep)) {
        throw new IllegalStateException("Missing capability-providing extension: " + dep);
    }
}

try {
    quarkusBuild();
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("The following capabilities have been required but not provided")) {
        // parse missing capability names and add the providing extensions
    }
    throw e;
}

When it happens

Trigger: During CapabilityAggregationStep.aggregateCapabilities, after processing all capability providers/builders, the CapabilityErrors build item is non-empty — i.e. some quarkus.* capability was requested by an extension or user config but no active extension provides it.

Common situations: Adding an extension that requires another capability (e.g. a datasource or transaction capability) without adding the extension that provides it; excluding/evicting an extension via quarkus.<ext>.enabled=false while another still requires its capability; dependency conflicts that silently dropped a provider extension; typos in capability names in user build steps.

Related errors

• Multiple extensions registered a feature of the same name: $
• Failed to open path tree with root %s
• %s is marked @Record but does not inject an @Recorder object
• Unknown recorder constructor parameter: %s in recorder %s
• Dev services for ${request.getName()} requires a startable s

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