quarkusio/quarkus · error · ConfigurationException

The Agroal extension is missing and it is required when a Qu

Error message

The Agroal extension is missing and it is required when a Quartz JDBC store is used.

What it means

A Quarkus ConfigurationException thrown by the QuartzProcessor driver build step at build time when a Quartz JDBC job store is configured (quarkus.quartz.store-type=jdbc) but the Agroal extension (which provides datasource/Connection pooling) is not present in the application. The JDBC job store needs a datasource to persist job state, so the build fails with this explicit message.

Source

Thrown at extensions/quartz/deployment/src/main/java/io/quarkus/quartz/deployment/QuartzProcessor.java:135

        if (config.storeType().isDbStore()) {
            return new NativeImageProxyDefinitionBuildItem(Connection.class.getName());
        }
        return null;
    }

    @BuildStep
    QuartzJDBCDriverDialectBuildItem driver(List<JdbcDataSourceBuildItem> jdbcDataSourceBuildItems,
            QuartzBuildTimeConfig config, Capabilities capabilities, CombinedIndexBuildItem indexBuildItem) {
        if (!config.storeType().isDbStore()) {
            if (config.clustered()) {
                throw new ConfigurationException("Clustered jobs configured with unsupported job store option");
            }
            // No DB storage, the driver can stay empty, and we don't need data sources either
            return new QuartzJDBCDriverDialectBuildItem(Optional.empty(), null);
        }

        if (capabilities.isMissing(Capability.AGROAL)) {
            throw new ConfigurationException(
                    "The Agroal extension is missing and it is required when a Quartz JDBC store is used.");
        }

        Optional<String> driverDelegate = config.driverDelegate();
        if (driverDelegate.isPresent()) {
            // user-specified custom delegate
            IndexView indexView = indexBuildItem.getIndex();
            ClassInfo customDelegate = indexView.getClassByName(driverDelegate.get());
            if (customDelegate == null) {
                String message = String.format(
                        "Custom JDBC delegate implementation class '%s' was not found in Jandex index. " +
                                "Make sure the dependency containing this class has proper marker file enabling discovery. " +
                                "Alternatively, you can index a dependency using IndexDependencyBuildItem.",
                        driverDelegate.get());
                throw new ConfigurationException(message);
            } else {
                // any custom implementation needs to be a subclass of known Quarkus delegate
                boolean implementsKnownDelegate = false;

View on GitHub (pinned to e1c734241f)

Solutions

Add the Agroal extension to the project: mvn quarkus:add-extension -Dextensions="agroal" (or add io.quarkus:quarkus-agroal to pom.xml).
Add the matching JDBC driver extension, e.g. quarkus-jdbc-postgresql, and configure quarkus.datasource.jdbc.url / username / password.
If you don't need DB-backed job storage, set quarkus.quartz.store-type=memory instead (and drop clustered=true).
Rebuild and confirm the capability appears via the application's capability list (quarkus insert-dev or build log).

Example fix

// before (pom.xml)
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-quartz</artifactId>
</dependency>

// after
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-quartz</artifactId>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-agroal</artifactId>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>

Defensive patterns

Strategy: validation

Validate before calling

// Verify required extensions are on the classpath before enabling the JDBC store
String storeType = ConfigProvider.getConfig()
    .getOptionalValue("quarkus.quartz.store-type", String.class).orElse("memory");
if ("jdbc".equalsIgnoreCase(storeType)) {
    try {
        Class.forName("io.quarkus.agroal.runtime.AgroalDataSourceSupport");
    } catch (ClassNotFoundException e) {
        throw new IllegalStateException(
            "quarkus.quartz.store-type=jdbc requires the quarkus-agroal extension (and a JDBC driver extension)");
    }
}

Prevention

Add quarkus-agroal and a quarkus-jdbc-<database> extension whenever you set store-type=jdbc.
Use mvn quarkus:add-extension -Dextensions="agroal,jdbc-postgresql" to avoid manual pom edits.
Run a build after dependency cleanup to catch capability checks early rather than in CI.
If DB storage isn't required, keep store-type=memory and avoid the extra extensions.

When it happens

Trigger: quarkus.quartz.store-type=jdbc (or resolves to a DB store) while the build capabilities check capabilities.isMissing(Capability.AGROAL) is true — i.e. quarkus-agroal / a database driver extension is not among the application dependencies.

Common situations: Enabling the JDBC store but forgetting to add the quarkus-agroal (and a quarkus-jdbc-<db> driver) dependency; a dependency was removed or excluded during a refactor; using quarkus-quartz in a minimal app without the datasource extensions.

Related errors

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