{"record":{"id":"f8e498b0e48213de","repo":"quarkusio/quarkus","slug":"unable-to-load-the-datasource-driver-drivername","errorCode":null,"errorMessage":"Unable to load the datasource driver <driverName> for the <fullDataSourceName>","messagePattern":"Unable to load the datasource driver <driverName> for the <fullDataSourceName>","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"extensions/agroal/deployment/src/main/java/io/quarkus/agroal/deployment/component/DataSourceDefinitionBlockingProcessor.java","lineNumber":213,"sourceCode":"                java.sql.ResultSet.class.getName(),\n                java.sql.ResultSet[].class.getName()).build());\n\n        // Enable SSL support by default\n        sslNativeSupport.produce(new ExtensionSslNativeSupportBuildItem(Feature.AGROAL.getName()));\n    }\n\n    private static void validateBuildTimeConfig(JdbcDataSourceDefinitionBuildItem aggregatedConfig) {\n        DataSourceJdbcBuildTimeConfig jdbcBuildTimeConfig = aggregatedConfig.getJdbcConfig();\n\n        String fullDataSourceName = aggregatedConfig.isDefault() ? \"default datasource\"\n                : \"datasource named '\" + aggregatedConfig.getName() + \"'\";\n\n        String driverName = aggregatedConfig.getResolvedDriverClass();\n        Class<?> driver;\n        try {\n            driver = Class.forName(driverName, true, Thread.currentThread().getContextClassLoader());\n        } catch (ClassNotFoundException e) {\n            throw new ConfigurationException(\n                    \"Unable to load the datasource driver \" + driverName + \" for the \" + fullDataSourceName, e);\n        }\n        if (jdbcBuildTimeConfig.transactions() == TransactionIntegration.XA) {\n            if (!XADataSource.class.isAssignableFrom(driver)) {\n                throw new ConfigurationException(\n                        \"Driver is not an XA dataSource, while XA has been enabled in the configuration of the \"\n                                + fullDataSourceName + \": either disable XA or switch the driver to an XADataSource\");\n            }\n        } else {\n            if (driver != null && !javax.sql.DataSource.class.isAssignableFrom(driver)\n                    && !Driver.class.isAssignableFrom(driver)) {\n                if (aggregatedConfig.isDefault()) {\n                    throw new ConfigurationException(\n                            \"Driver \" + driverName\n                                    + \" 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\");\n                } else {\n                    throw new ConfigurationException(\n                            \"Driver \" + driverName","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/agroal/deployment/src/main/java/io/quarkus/agroal/deployment/component/DataSourceDefinitionBlockingProcessor.java#L195-L231","documentation":"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.","triggerScenarios":"validateBuildTimeConfig() (called from defineJdbcDataSources) executes Class.forName(driverName, true, TCCL) where driverName = aggregatedConfig.getResolvedDriverClass(); a ClassNotFoundException is wrapped into this ConfigurationException.","commonSituations":"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.","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."],"exampleFix":"// before\nquarkus.datasource.db-kind=postgresql\nquarkus.datasource.jdbc.driver=org.postgreqsql.Driver // typo, class missing\n// after\nquarkus.datasource.db-kind=postgresql\nquarkus.datasource.jdbc.driver=org.postgresql.Driver","handlingStrategy":"validation","validationCode":"String driver = ConfigProvider.getConfig().getValue(\"quarkus.datasource.jdbc.driver\", String.class);\ntry { Class.forName(driver, true, Thread.currentThread().getContextClassLoader()); }\ncatch (ClassNotFoundException e) { throw new IllegalStateException(\"Driver not on classpath: \" + driver); }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add the JDBC driver extension/dependency before setting quarkus.datasource.jdbc.driver.","Prefer db-kind-based driver resolution over manual driver class configuration."],"tags":["quarkus","agroal","jdbc","datasource","classpath","build-time"],"backgroundTag":"jdbc-driver-class-not-found","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}