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

Add the Quarkus JDBC driver extension for your database: io.quarkus:quarkus-jdbc-postgresql (or -mysql, -mariadb, -h2, -mssql, -oracle)

quarkusio/quarkus · critical · RuntimeException

Unable to load the datasource driver <resolvedDriverClass> f

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.

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)

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)

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

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

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

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