quarkusio/quarkus · error · ConfigurationException

Custom JDBC delegate implementation with name '%s' needs to

Error message

Custom JDBC delegate implementation with name '%s' needs to be a subclass of one of the existing Quarkus delegates such as io.quarkus.quartz.runtime.jdbc.QuarkusPostgreSQLDelegate.

What it means

A custom driver-delegate class was found in the Jandex index, but it is not a subclass of any of Quarkus's known Quartz JDBC delegates (QuarkusMSSQLDelegate, QuarkusPostgreSQLDelegate, QuarkusDBv8Delegate, QuarkusStdJDBCDelegate, QuarkusHSQLDBDelegate). Quarkus requires the extension point to extend one of these known implementations so it can validate the delegate hierarchy and wire it correctly at runtime.

Source

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

                        driverDelegate.get());
                throw new ConfigurationException(message);
            } else {
                // any custom implementation needs to be a subclass of known Quarkus delegate
                boolean implementsKnownDelegate = false;
                for (DotName knownImplementation : Set.of(DELEGATE_MSSQL, DELEGATE_POSTGRESQL, DELEGATE_DB2V8, DELEGATE_STDJDBC,
                        DELEGATE_HSQLDB)) {
                    for (ClassInfo classInfo : indexView.getAllKnownSubclasses(knownImplementation)) {
                        if (classInfo.name().equals(customDelegate.name())) {
                            implementsKnownDelegate = true;
                            break;
                        }
                    }
                }
                if (!implementsKnownDelegate) {
                    String message = String.format(
                            "Custom JDBC delegate implementation with name '%s' needs to be a subclass of one of the existing Quarkus delegates such as io.quarkus.quartz.runtime.jdbc.QuarkusPostgreSQLDelegate.",
                            driverDelegate.get());
                    throw new ConfigurationException(message);
                }
            }
            // A custom delegate implementation, we don't need to check datasources
            return new QuartzJDBCDriverDialectBuildItem(driverDelegate, null);
        } else {
            if (config.deferDatasourceCheck()) {
                // if defer is set to true and there is a DS name, throw an exception
                if (config.dataSourceName().isPresent()) {
                    String message = String.format(
                            "Quartz datasource resolution can be either deferred to runtime or specified at build time but not both. Related properties are quarkus.quartz.defer-datasource-check=%s and quarkus.quartz.datasource=%s",
                            config.deferDatasourceCheck(), config.dataSourceName());
                    throw new ConfigurationException(message);
                }
                // Defer driver resolution to runtime
                List<JDBCDataSource> dataSources = new ArrayList<>();
                for (JdbcDataSourceBuildItem jdbcDataSourceBuildItem : jdbcDataSourceBuildItems) {
                    dataSources.add(new JDBCDataSource(jdbcDataSourceBuildItem.getName(), jdbcDataSourceBuildItem.isDefault(),
                            jdbcDataSourceBuildItem.getDbKind()));

View on GitHub (pinned to e1c734241f)

Solutions

1. Make the custom delegate extend io.quarkus.quartz.runtime.jdbc.QuarkusStdJDBCDelegate, QuarkusPostgreSQLDelegate, QuarkusMSSQLDelegate, QuarkusDBv8Delegate, or QuarkusHSQLDBDelegate (matching your database).
2. If extending the plain Quartz StdJDBCDelegate, switch the superclass to io.quarkus.quartz.runtime.jdbc.QuarkusStdJDBCDelegate and keep custom logic in overridden methods.
3. If no customization is needed, remove quarkus.quartz.driver-delegate and let Quarkus auto-select the delegate from the datasource db-kind.

Example fix

// before
public class MyDelegate extends StdJDBCDelegate { /* ... */ }

// after
import io.quarkus.quartz.runtime.jdbc.QuarkusStdJDBCDelegate;
public class MyDelegate extends QuarkusStdJDBCDelegate { /* ... */ }

Class<?> c = Class.forName("com.example.MyDelegate", false,
    Thread.currentThread().getContextClassLoader());
boolean ok = io.quarkus.quartz.runtime.jdbc.QuarkusStdJDBCDelegate.class.isAssignableFrom(c)
    || io.quarkus.quartz.runtime.jdbc.QuarkusPostgreSQLDelegate.class.isAssignableFrom(c);
if (!ok) throw new IllegalStateException("Delegate must extend a Quarkus Quartz JDBC delegate");

static boolean isQuarkusDelegate(Class<?> c) {
    return io.quarkus.quartz.runtime.jdbc.QuarkusStdJDBCDelegate.class.isAssignableFrom(c);
}

When it happens

Trigger: Setting quarkus.quartz.driver-delegate to a class that extends plain org.quartz.impl.jdbcjobstore.StdJDBCDelegate instead of a Quarkus wrapper, or to any unrelated indexed class, while quarkus.quartz.store-type is a DB store.

Common situations: Migrating a plain Quartz/SE setup where the custom delegate extended the Quartz StdJDBCDelegate directly; writing a delegate from scratch instead of extending the Quarkus wrapper; refactoring that changed the parent class away from a Quarkus delegate.

Related errors

• Custom JDBC delegate implementation class '%s' was not found
• Clustered jobs configured with unsupported job store option
• The Agroal extension is missing and it is required when a Qu
• Quartz datasource resolution can be either deferred to runti
• JDBC Store configured but the '%s' datasource is not configu

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