quarkusio/quarkus · error · ConfigurationException

Could not guess the dialect from the database kind '${dbKind

Error message

Could not guess the dialect from the database kind '${dbKind}'. Add an explicit 'quarkus.hibernate-orm."<persistence-unit-name>".dialect' property.

What it means

Quarkus tries to infer the Hibernate dialect from the configured datasource's db-kind and product name/version. When the database kind is unknown or provides no product name, the dialect cannot be guessed and ConfigurationException is thrown, asking for an explicit dialect property.

Source

Thrown at extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/util/HibernateProcessorSupport.java:94

        if (dbKind.isPresent() || explicitDialect.isPresent()) {
            for (DatabaseKindDialectBuildItem item : dbKindDialectBuildItems) {
                if (dbKind.isPresent() && DatabaseKind.is(dbKind.get(), item.getDbKind())
                        || explicitDialect.isPresent() && item.getMatchingDialects().contains(explicitDialect.get())) {
                    if (dbKind.isEmpty()) {
                        dbKind = Optional.ofNullable(item.getDbKind());
                    }
                    dbProductName = item.getDatabaseProductName();
                    if (dbProductName.isEmpty() && explicitDialect.isEmpty()) {
                        dialect = item.getDialectOptional();
                    }
                    if (dbVersion.isEmpty()) {
                        dbProductVersion = item.getDefaultDatabaseProductVersion();
                    }
                    break;
                }
            }
            if (dialect.isEmpty() && dbProductName.isEmpty()) {
                throw new ConfigurationException(
                        "Could not guess the dialect from the database kind '"
                                + dbKind.get()
                                + "'. Add an explicit '"
                                + HibernateOrmRuntimeConfig.puPropertyKey(persistenceUnitName, "dialect")
                                + "' property.");
            }
        }

        if (dialect.isPresent()) {
            puPropertiesCollector.accept(AvailableSettings.DIALECT, dialect.get());
        } else if (dbProductName.isPresent()) {
            puPropertiesCollector.accept(AvailableSettings.JAKARTA_HBM2DDL_DB_NAME, dbProductName.get());
        }

        if (dbProductVersion.isPresent()) {
            puPropertiesCollector.accept(AvailableSettings.JAKARTA_HBM2DDL_DB_VERSION, dbProductVersion.get());
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Set an explicit dialect: quarkus.hibernate-orm."<pu>".dialect=org.hibernate.dialect.PostgreSQLDialect (or appropriate)
2. Verify quarkus.datasource.db-kind is a supported value (postgresql, mysql, mariadb, mssql, db2, oracle, h2, etc.)
3. If using a custom Dialect, ensure it is on the classpath and the fully-qualified class name is correct

Example fix

// before
quarkus.datasource.db-kind=other
// after
quarkus.datasource.db-kind=postgresql
# or, if the kind must stay custom:
quarkus.hibernate-orm.dialect=org.hibernate.dialect.PostgreSQLDialect

// Confirm db-kind maps to a known dialect before relying on auto-detection
Set<String> supported = Set.of("postgresql","mysql","mariadb","mssql","db2","oracle","h2","derby");
if (!supported.contains(dbKind))
    throw new IllegalStateException("Set quarkus.hibernate-orm.dialect explicitly for " + dbKind);

When it happens

Trigger: setDialectAndStorageEngine resolves the db kind but ends with an empty dialect and empty dbProductName (e.g. dbKind present but no dialect mapping and no database product info from the datasource build item).

Common situations: Using a custom/uncommon db-kind; datasource configured with db-kind that has no built-in dialect mapping; Quarkus version where the DB kind mapping is missing; overriding product name detection fails for a proxy or wrapper driver.

Related errors

• Cannot find ORM mapping file '${mappingFileName}' in the cla
• Missing attribute '${nodeName}.class'
• Annotation ${dotName} was not expected on a target of kind $
• Type ${className} must be annotated with @Embeddable, becaus
• Multiple ${AdditionalPersistenceUnitBuildItem} for persisten

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