What causes "Unable to load the datasource driver for the " in quarkusio/quarkus?

Add the JDBC driver dependency or corresponding Quarkus driver extension (e.g. quarkus-jdbc-postgresql) to the project.

quarkusio/quarkus · error · ConfigurationException

Unable to load the datasource driver <driverName> for the <f

Error message

Unable to load the datasource driver <driverName> for the <fullDataSourceName>

What it means

At build time, Agroal's DataSourceDefinitionBlockingProcessor.validateBuildTimeConfig() loads the JDBC driver class resolved for a datasource via Class.forName. If the driver class named in quarkus.datasource.<name>.jdbc.driver cannot be found on the build classpath, a ConfigurationException naming the driver and datasource is thrown, aborting the build.

Source

Thrown at extensions/agroal/deployment/src/main/java/io/quarkus/agroal/deployment/component/DataSourceDefinitionBlockingProcessor.java:213

                java.sql.ResultSet.class.getName(),
                java.sql.ResultSet[].class.getName()).build());

        // Enable SSL support by default
        sslNativeSupport.produce(new ExtensionSslNativeSupportBuildItem(Feature.AGROAL.getName()));
    }

    private static void validateBuildTimeConfig(JdbcDataSourceDefinitionBuildItem aggregatedConfig) {
        DataSourceJdbcBuildTimeConfig jdbcBuildTimeConfig = aggregatedConfig.getJdbcConfig();

        String fullDataSourceName = aggregatedConfig.isDefault() ? "default datasource"
                : "datasource named '" + aggregatedConfig.getName() + "'";

        String driverName = aggregatedConfig.getResolvedDriverClass();
        Class<?> driver;
        try {
            driver = Class.forName(driverName, true, Thread.currentThread().getContextClassLoader());
        } catch (ClassNotFoundException e) {
            throw new ConfigurationException(
                    "Unable to load the datasource driver " + driverName + " for the " + fullDataSourceName, e);
        }
        if (jdbcBuildTimeConfig.transactions() == TransactionIntegration.XA) {
            if (!XADataSource.class.isAssignableFrom(driver)) {
                throw new ConfigurationException(
                        "Driver is not an XA dataSource, while XA has been enabled in the configuration of the "
                                + fullDataSourceName + ": either disable XA or switch the driver to an XADataSource");
            }
        } else {
            if (driver != null && !javax.sql.DataSource.class.isAssignableFrom(driver)
                    && !Driver.class.isAssignableFrom(driver)) {
                if (aggregatedConfig.isDefault()) {
                    throw new ConfigurationException(
                            "Driver " + driverName
                                    + " is an XA datasource, but XA transactions have not been enabled on the default datasource; please either set 'quarkus.datasource.jdbc.transactions=xa' or switch to a standard non-XA JDBC driver implementation");
                } else {
                    throw new ConfigurationException(
                            "Driver " + driverName

View on GitHub (pinned to e1c734241f)

Solutions

Add the JDBC driver dependency or corresponding Quarkus driver extension (e.g. quarkus-jdbc-postgresql) to the project.
Correct the driver class name in quarkus.datasource.jdbc.driver (check spelling/package).
Remove the explicit driver property if the db-kind is enough for driver resolution.

Example fix

// before
quarkus.datasource.db-kind=postgresql
quarkus.datasource.jdbc.driver=org.postgreqsql.Driver // typo, class missing
// after
quarkus.datasource.db-kind=postgresql
quarkus.datasource.jdbc.driver=org.postgresql.Driver

Defensive patterns

Strategy: validation

Validate before calling

String driver = ConfigProvider.getConfig().getValue("quarkus.datasource.jdbc.driver", String.class);
try { Class.forName(driver, true, Thread.currentThread().getContextClassLoader()); }
catch (ClassNotFoundException e) { throw new IllegalStateException("Driver not on classpath: " + driver); }

Prevention

Add the JDBC driver extension/dependency before setting quarkus.datasource.jdbc.driver.
Prefer db-kind-based driver resolution over manual driver class configuration.

When it happens

Trigger: validateBuildTimeConfig() (called from defineJdbcDataSources) executes Class.forName(driverName, true, TCCL) where driverName = aggregatedConfig.getResolvedDriverClass(); a ClassNotFoundException is wrapped into this ConfigurationException.

Common situations: Setting quarkus.datasource.jdbc.driver to a class from a JDBC driver not on the classpath (missing driver extension/dependency); typo in the driver class name; using a driver artifact without the class at build time.

Related errors

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