{"record":{"id":"8b4174d3ce517323","repo":"quarkusio/quarkus","slug":"unable-to-load-the-datasource-driver-resolveddriv","errorCode":null,"errorMessage":"Unable to load the datasource driver <resolvedDriverClass> for datasource <dataSourceName>","messagePattern":"Unable to load the datasource driver <resolvedDriverClass> for datasource <dataSourceName>","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/DataSources.java","lineNumber":169,"sourceCode":"        DataSourceRuntimeConfig dataSourceRuntimeConfig = dataSourcesRuntimeConfig.dataSources().get(dataSourceName);\n\n        DataSourceJdbcRuntimeConfig dataSourceJdbcRuntimeConfig = dataSourcesJdbcRuntimeConfig\n                .dataSources().get(dataSourceName).jdbc();\n        if (!dataSourceJdbcRuntimeConfig.url().isPresent()) {\n            throw new IllegalArgumentException(\n                    \"Datasource \" + dataSourceName + \" does not have a JDBC URL and should not be created\");\n        }\n\n        // we first make sure that all available JDBC drivers are loaded in the current TCCL\n        loadDriversInTCCL();\n\n        AgroalDataSourceSupport.Entry matchingSupportEntry = agroalDataSourceSupport.entries.get(dataSourceName);\n        String resolvedDriverClass = matchingSupportEntry.resolvedDriverClass;\n        Class<?> driver;\n        try {\n            driver = Class.forName(resolvedDriverClass, true, Thread.currentThread().getContextClassLoader());\n        } catch (ClassNotFoundException e) {\n            throw new RuntimeException(\n                    \"Unable to load the datasource driver \" + resolvedDriverClass + \" for datasource \" + dataSourceName, e);\n        }\n\n        String jdbcUrl = dataSourceJdbcRuntimeConfig.url().get();\n\n        String resolvedDbKind = matchingSupportEntry.resolvedDbKind;\n        AgroalConnectionConfigurer agroalConnectionConfigurer = Arc.container()\n                .instance(AgroalConnectionConfigurer.class, new JdbcDriverLiteral(resolvedDbKind))\n                .orElse(new UnknownDbAgroalConnectionConfigurer());\n\n        AgroalDataSourceConfigurationSupplier dataSourceConfiguration = new AgroalDataSourceConfigurationSupplier();\n\n        // Set pool-less mode\n        if (!dataSourceJdbcRuntimeConfig.poolingEnabled()) {\n            dataSourceConfiguration.dataSourceImplementation(DataSourceImplementation.AGROAL_POOLLESS);\n        }\n\n        AgroalConnectionPoolConfigurationSupplier poolConfiguration = dataSourceConfiguration.connectionPoolConfiguration();","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/DataSources.java#L151-L187","documentation":"After resolving the driver class name from the build-time Agroal support entry, DataSources tries Class.forName with the context classloader and fails. This means the JDBC driver class is not on the runtime classpath of the application.","triggerScenarios":"createDataSource calls Class.forName(resolvedDriverClass, true, TCCL) and throws ClassNotFoundException, wrapped in RuntimeException naming the datasource and resolved driver class.","commonSituations":"Forgot the driver dependency (e.g. quarkus-jdbc-postgresql) in pom.xml; driver present only in provided/test scope; custom driver class name typo in quarkus.datasource.<name>.jdbc.driver; running in native mode without driver reflection registration.","solutions":["Add the Quarkus JDBC driver extension for your database: io.quarkus:quarkus-jdbc-postgresql (or -mysql, -mariadb, -h2, -mssql, -oracle)","If using a custom driver, set quarkus.datasource.<name>.jdbc.driver to the fully qualified class name and add its artifact as a compile-scope dependency","Check dependency scope: the driver must not be provided/test scope in the deployable artifact","Rebuild the application after adding the dependency (mvn clean package)"],"exampleFix":"<!-- before: no driver dependency -->\n<!-- after -->\n<dependency>\n  <groupId>io.quarkus</groupId>\n  <artifactId>quarkus-jdbc-postgresql</artifactId>\n</dependency>","handlingStrategy":"validation","validationCode":"try { Class.forName(\"org.postgresql.Driver\", true, Thread.currentThread().getContextClassLoader()); } catch (ClassNotFoundException e) { throw new IllegalStateException(\"JDBC driver missing from classpath\"); }","typeGuard":null,"tryCatchPattern":"try { DataSource ds = dataSourceCreator.apply(name); } catch (RuntimeException e) { if (e.getMessage() != null && e.getMessage().startsWith(\"Unable to load the datasource driver\")) { /* add driver dependency / fail fast */ } throw e; }","preventionTips":["Add the matching quarkus-jdbc-<db> extension, not a bare driver jar","Check dependency scopes (no provided/test-only drivers)","After changing driver deps, run mvn clean package","For native builds confirm driver registration via the extension"],"tags":["quarkus","datasource","jdbc","classpath","driver"],"backgroundTag":"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"}