quarkusio/quarkus · error · ConfigurationException

Custom JDBC delegate implementation class '%s' was not found

Error message

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.

What it means

When quarkus.quartz.store-type is a JDBC store and quarkus.quartz.driver-delegate points to a custom class, the QuartzProcessor build step looks that class up in the application's Jandex index at build time. If the class is not present in the index, the processor cannot validate or register it, so it fails the build with this ConfigurationException. This typically means the class lives in a dependency that was not indexed for discovery.

Source

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

        }

        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;
                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);
                }

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the quarkus.quartz.driver-delegate value is the exact fully-qualified class name and that the class exists on the deployment classpath.
2. Move the delegate class into your application (e.g. src/main/java) so Jandex indexes it automatically.
3. If the class is in a third-party jar, register io.quarkus.deployment.builditem.IndexDependencyBuildItem in a build step, or use quarkus.index-dependency.<name>.group-id / .artifact-id config.
4. If you don't need a custom delegate, remove the driver-delegate property and let Quarkus guess the driver from the datasource db-kind.

Example fix

// before (application.properties)
quarkus.quartz.driver-delegate=com.example.mylib.MyDelegate
// class lives in unindexed jar

// after
quarkus.index-dependency.mylib.group-id=com.example
quarkus.index-dependency.mylib.artifact-id=mylib
quarkus.quartz.driver-delegate=com.example.mylib.MyDelegate

// Ensure the class is indexed: keep it in src/main/java, or in a build step:
// @BuildStep
// IndexDependencyBuildItem indexMyLib() {
//     return new IndexDependencyBuildItem("com.example", "mylib");
// }
// or via config: quarkus.index-dependency.mylib.group-id / .artifact-id
// Classpath sanity check:
try {
    Class.forName("com.example.mylib.MyDelegate", false,
        Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("driver-delegate class missing: " + e.getMessage());
}

When it happens

Trigger: Setting quarkus.quartz.driver-delegate=<fqcn> with quarkus.quartz.store-type=jdbc-job-store (or clustered) when the named class is not in any indexed application dependency: the class is in a third-party jar without a Jandex marker file (META-INF/jandex.idx) and no IndexDependencyBuildItem was produced; or the FQCN is misspelled; or the class is only present at runtime, not at build time.

Common situations: Using a vendor delegate from a shared library that was never indexed; typos in the driver-delegate property; upgrading Quarkus where a previously auto-indexed dependency lost its marker file; copying a config from another project where the delegate class existed in the app itself.

Related errors

• Custom JDBC delegate implementation with name '%s' needs to
• Invalid type:
• Injected class not found in index:
• The original implementation class of a gRPC service not foun
• Couldn't find id field of ${classInfo}

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