quarkusio/quarkus · critical · RuntimeException

Unable to load the datasource driver

Error message

Unable to load the datasource driver <resolvedDriverClass> for datasource <dataSourceName>

What it means

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.

Solutions

1. Add the Quarkus JDBC driver extension for your database: io.quarkus:quarkus-jdbc-postgresql (or -mysql, -mariadb, -h2, -mssql, -oracle)
2. 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
3. Check dependency scope: the driver must not be provided/test scope in the deployable artifact
4. Rebuild the application after adding the dependency (mvn clean package)

Example fix

<!-- before: no driver dependency -->
<!-- after -->
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>

try { Class.forName("org.postgresql.Driver", true, Thread.currentThread().getContextClassLoader()); } catch (ClassNotFoundException e) { throw new IllegalStateException("JDBC driver missing from classpath"); }

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

When it happens

Trigger: createDataSource calls Class.forName(resolvedDriverClass, true, TCCL) and throws ClassNotFoundException, wrapped in RuntimeException naming the datasource and resolved driver class.

Common situations: 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.

Related errors

• Unable to load the datasource driver
• Datasource does not have a JDBC URL and should not be…
• JDBC Store configured but
• A Datasource was configured as Connection Pool, but it's…
• Additional application archives can only be provided from…

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

Appendix: source

Thrown at extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/DataSources.java:169

        DataSourceRuntimeConfig dataSourceRuntimeConfig = dataSourcesRuntimeConfig.dataSources().get(dataSourceName);

        DataSourceJdbcRuntimeConfig dataSourceJdbcRuntimeConfig = dataSourcesJdbcRuntimeConfig
                .dataSources().get(dataSourceName).jdbc();
        if (!dataSourceJdbcRuntimeConfig.url().isPresent()) {
            throw new IllegalArgumentException(
                    "Datasource " + dataSourceName + " does not have a JDBC URL and should not be created");
        }

        // we first make sure that all available JDBC drivers are loaded in the current TCCL
        loadDriversInTCCL();

        AgroalDataSourceSupport.Entry matchingSupportEntry = agroalDataSourceSupport.entries.get(dataSourceName);
        String resolvedDriverClass = matchingSupportEntry.resolvedDriverClass;
        Class<?> driver;
        try {
            driver = Class.forName(resolvedDriverClass, true, Thread.currentThread().getContextClassLoader());
        } catch (ClassNotFoundException e) {
            throw new RuntimeException(
                    "Unable to load the datasource driver " + resolvedDriverClass + " for datasource " + dataSourceName, e);
        }

        String jdbcUrl = dataSourceJdbcRuntimeConfig.url().get();

        String resolvedDbKind = matchingSupportEntry.resolvedDbKind;
        AgroalConnectionConfigurer agroalConnectionConfigurer = Arc.container()
                .instance(AgroalConnectionConfigurer.class, new JdbcDriverLiteral(resolvedDbKind))
                .orElse(new UnknownDbAgroalConnectionConfigurer());

        AgroalDataSourceConfigurationSupplier dataSourceConfiguration = new AgroalDataSourceConfigurationSupplier();

        // Set pool-less mode
        if (!dataSourceJdbcRuntimeConfig.poolingEnabled()) {
            dataSourceConfiguration.dataSourceImplementation(DataSourceImplementation.AGROAL_POOLLESS);
        }

        AgroalConnectionPoolConfigurationSupplier poolConfiguration = dataSourceConfiguration.connectionPoolConfiguration();

View on GitHub (pinned to e1c734241f)