quarkusio/quarkus · error · ConfigurationException

Unable to find a JDBC driver corresponding to the database k

Error message

Unable to find a JDBC driver corresponding to the database kind '%s' for the %s (available: '%s'). Check if it's a typo, otherwise provide a suitable JDBC driver extension, define the driver manually, or disable the JDBC datasource by adding '%s=false' to your configuration if you don't need it.

What it means

When no explicit driver is configured, Agroal resolves a driver from registered JdbcDriverBuildItems by matching the datasource's db-kind. resolveDriver() throws this ConfigurationException when no registered driver matches the database kind, listing the available kinds and suggesting how to disable the JDBC datasource.

Source

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

        if (dataSourceJdbcBuildTimeConfig.driver().isPresent()) {
            return dataSourceJdbcBuildTimeConfig.driver().get();
        }

        Optional<JdbcDriverBuildItem> matchingJdbcDriver = jdbcDriverBuildItems.stream()
                .filter(i -> dbKind.equals(i.getDbKind()))
                .findFirst();

        if (matchingJdbcDriver.isPresent()) {
            if (io.quarkus.agroal.runtime.TransactionIntegration.XA == dataSourceJdbcBuildTimeConfig.transactions()) {
                if (matchingJdbcDriver.get().getDriverXAClass().isPresent()) {
                    return matchingJdbcDriver.get().getDriverXAClass().get();
                }
            } else {
                return matchingJdbcDriver.get().getDriverClass();
            }
        }

        throw new ConfigurationException(String.format(
                "Unable to find a JDBC driver corresponding to the database kind '%s' for the %s (available: '%s'). "
                        + "Check if it's a typo, otherwise provide a suitable JDBC driver extension, define the driver manually,"
                        + " or disable the JDBC datasource by adding '%s=false' to your configuration if you don't need it.",
                dbKind, DataSourceUtil.isDefault(dataSourceName) ? "default datasource" : "datasource '" + dataSourceName + "'",
                jdbcDriverBuildItems.stream().map(JdbcDriverBuildItem::getDbKind).collect(Collectors.joining("','")),
                DataSourceUtil.dataSourcePropertyKey(dataSourceName, "jdbc")));
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Fix the db-kind value to one of the listed available kinds (e.g. postgresql, mariadb, mssql, h2).
Add the matching JDBC driver extension (e.g. quarkus-jdbc-postgresql).
Or define the driver manually via quarkus.datasource.jdbc.driver and add a driver dependency.
Or disable the JDBC datasource with quarkus.datasource.jdbc=false (or quarkus.datasource.<name>.jdbc=false) if not needed.

Example fix

// before
quarkus.datasource.db-kind=postgres // unknown kind
// after
quarkus.datasource.db-kind=postgresql

Defensive patterns

Strategy: validation

Validate before calling

String kind = ConfigProvider.getConfig().getValue("quarkus.datasource.db-kind", String.class);
Set<String> known = Set.of("postgresql", "h2", "mariadb", "mysql", "mssql", "oracle", "db2", "derby");
if (!known.contains(kind)) throw new IllegalStateException("Unknown db-kind: " + kind);

Prevention

Use exact db-kind values (postgresql, not postgres).
Add the corresponding quarkus-jdbc-* extension for the chosen db-kind.
Disable the JDBC datasource (quarkus.datasource.jdbc=false) when only reactive access is needed.

When it happens

Trigger: definition() -> resolveDriver() finds no matchingJdbcDriver for dbKind of dataSourceName; String.format builds the message with the kind, datasource description, available db-kinds, and the quarkus.datasource.jdbc (or named) disable key.

Common situations: db-kind typo (e.g. 'postgres' instead of 'postgresql'); missing JDBC driver extension (only reactive driver present); using an unsupported database kind with no manual driver defined.

Related errors

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