quarkusio/quarkus · error · ConfigurationException

Deferred datasource name is missing - you can configure it v

Error message

Deferred datasource name is missing - you can configure it via quarkus.quartz.deferred-datasource-name.

What it means

When Quarkus is configured with a Quartz store requiring a database (store-type=jdbc / deferred datasources), QuartzSupport requires the name of the datasource Quartz should use. If dataSources are supplied but runtimeConfig.deferredDatasourceName() is empty, it throws this SmallRye Config ConfigurationException, failing the application start with a clear message.

Source

Thrown at extensions/quartz/runtime/src/main/java/io/quarkus/quartz/runtime/QuartzSupport.java:36

public class QuartzSupport {

    private final QuartzRuntimeConfig runtimeConfig;
    private final QuartzBuildTimeConfig buildTimeConfig;
    private final Optional<String> driverDialect;
    // <FQCN>#<method_name>
    private final Set<String> nonconcurrentMethods;

    public QuartzSupport(QuartzRuntimeConfig runtimeConfig, QuartzBuildTimeConfig buildTimeConfig,
            Optional<String> driverDialect, List<JDBCDataSource> dataSources, Set<String> nonconcurrentMethods) {
        this.runtimeConfig = runtimeConfig;
        this.buildTimeConfig = buildTimeConfig;
        this.nonconcurrentMethods = Set.copyOf(nonconcurrentMethods);

        if (dataSources == null) {
            this.driverDialect = driverDialect;
        } else {
            if (runtimeConfig.deferredDatasourceName().isEmpty()) {
                throw new ConfigurationException(
                        "Deferred datasource name is missing - you can configure it via quarkus.quartz.deferred-datasource-name.");
            }
            // Determine the driver dialect
            Optional<JDBCDataSource> selectedDataSource = dataSources.stream()
                    .filter(i -> runtimeConfig.deferredDatasourceName().get().equals(i.getName()))
                    .findFirst();

            if (!selectedDataSource.isPresent()) {
                String message = String.format(
                        "JDBC Store configured but the '%s' datasource is not configured properly. You can configure your datasource by following the guide available at: https://quarkus.io/guides/datasource",
                        runtimeConfig.deferredDatasourceName().isPresent() ? runtimeConfig.deferredDatasourceName().get()
                                : "default");
                throw new ConfigurationException(message);
            }

            String dataSourceKind = selectedDataSource.get().getDbKind();
            if (DatabaseKind.isPostgreSQL(dataSourceKind)) {
                this.driverDialect = Optional.of(QuarkusPostgreSQLDelegate.class.getName());

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.quartz.deferred-datasource-name=<your-datasource-name> in application.properties matching the configured Agroal datasource name
Confirm the datasource exists and its quarkus.datasource.<name> configuration is present and active
If no persistent store is needed, change quarkus.quartz.store-type back to memory so no datasource is required
Check property spelling/location (profile-specific files may hide or override the property)

Example fix

// before (application.properties)
quarkus.quartz.store-type=jdbc
# missing datasource name
// after
quarkus.quartz.store-type=jdbc
quarkus.quartz.deferred-datasource-name=my-ds
quarkus.datasource.my-ds.db-kind=postgresql
quarkus.datasource.my-ds.username=quartz
quarkus.datasource.my-ds.jdbc.url=jdbc:postgresql://localhost:5432/quartz

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast before Quarkus does: check the deferred datasource is configured
if (Set.of("jdbc", "todo-db").contains(cfg.storeType())
        && (cfg.deferredDatasourceName() == null || cfg.deferredDatasourceName().isEmpty())) {
    throw new IllegalArgumentException(
        "quarkus.quartz.deferred-datasource-name is required for store-type " + cfg.storeType());
}

Try / catch

try {
    application.start(); // or build QuartzSupport
} catch (Exception e) {
    if (e.getMessage() != null && e.getMessage().contains("Deferred datasource name is missing")) {
        LOG.error("Set quarkus.quartz.deferred-datasource-name to your Agroal datasource name");
    }
    throw e;
}

Prevention

Always pair store-type=jdbc/todo-db with quarkus.quartz.deferred-datasource-name
Ensure the named datasource exists under quarkus.datasource.<name>.*
Add a startup integration test that exercises the Quartz store config
Avoid mixing datasource names across profiles (dev/test/prod)

When it happens

Trigger: Building the QuartzSupport runtime config when dataSources are non-null (database-backed store selected) and quarkus.quartz.deferred-datasource-name is not set.

Common situations: Switching quarkus.quartz.store-type to a JDBC-backed store without setting the deferred datasource name; multiple datasources where the intended one is not named; copying config from docs but omitting the property; typo in the property name so it is never picked up.

Related errors

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