quarkusio/quarkus · error · ConfigurationException

Persistence unit '<persistenceUnitName>' was configured to r

Error message

Persistence unit '<persistenceUnitName>' was configured to run with a database version of at least '<buildTimeDbVersion>'[, (Quarkus default)], but the actual version is '<actualDbVersion>'. Consider upgrading your database. [ The minimum version supported by the <dialect> dialect is <minVersion>.] [ Alternatively, rebuild your application with '<property>=<version>' (but this may disable some features and/or impact performance negatively).] [ As a last resort, if you are certain your application will work correctly even though the database version is incorrect, disable the check with '<puProperty>=false'.]

What it means

At runtime, QuarkusRuntimeInitDialectFactory.checkActualDbVersion compares the real database version (from DialectResolutionInfo) with the build-time recorded minimum version. If the actual DB is older than what the dialect/PU was built against, it throws a ConfigurationException with a detailed message including the dialect's minimum supported version and remediation options.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/service/QuarkusRuntimeInitDialectFactory.java:128

            // but just let's be safe...
            if (datasourceName.isPresent()) {
                errorMessage.append(String.format(Locale.ROOT,
                        " Alternatively, rebuild your application with"
                                + " '%1$s=%2$s'"
                                + " (but this may disable some features and/or impact performance negatively).",
                        isFromPersistenceXml ? AvailableSettings.JAKARTA_HBM2DDL_DB_VERSION
                                : DataSourceUtil.dataSourcePropertyKey(datasourceName.get(), "db-version"),
                        DialectVersions.toString(actualDbVersion.get())));
            }
            if (!isFromPersistenceXml) {
                errorMessage.append(String.format(Locale.ROOT,
                        " As a last resort,"
                                + " if you are certain your application will work correctly even though the database version is incorrect,"
                                + " disable the check with"
                                + " '%1$s=false'.",
                        HibernateOrmRuntimeConfig.puPropertyKey(persistenceUnitName, "database.version-check.enabled")));
            }
            throw new ConfigurationException(errorMessage.toString());
        }
    }

    private Optional<DatabaseVersion> retrieveDbVersion(DialectResolutionInfoSource resolutionInfoSource) {
        try {
            var resolutionInfo = resolutionInfoSource == null ? null
                    // This may throw an exception if the DB cannot be reached, in particular with Hibernate Reactive.
                    : resolutionInfoSource.getDialectResolutionInfo();
            if (resolutionInfo == null) {
                return Optional.empty();
            }
            triedToRetrieveDbVersion = true;
            return Optional.of(dialect.determineDatabaseVersion(resolutionInfo));
        } catch (RuntimeException e) {
            LOG.warnf(e, "Persistence unit %1$s: Could not retrieve the database version to check it is at least %2$s",
                    persistenceUnitName, buildTimeDbVersion);
            return Optional.empty();
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Upgrade the database server to at least the recorded/minimum version (preferred, keeps all features and optimizations).
2. Rebuild the application with quarkus.hibernate-orm.<pu>.database.version=<olderVersion> (or database.default) so the dialect targets the actual server.
3. If you are certain your SQL works on the older DB, disable the check with quarkus.hibernate-orm.<pu>.database.version-check.enabled=false — accepting possible disabled features/perf impact.

Example fix

// before (built against newer DB, deployed to PostgreSQL 12)
# quarkus.hibernate-orm.database.version=15

// after
quarkus.hibernate-orm.database.version=12
# or explicitly:
# quarkus.hibernate-orm.database.version-check.enabled=false

// Compare actual DB version against expected before deploying
String expected = config.getValue("quarkus.hibernate-orm.database.version", String.class);
String actual = queryDbVersion(); // e.g. "select version()"
if (expected != null && versionCompare(actual, expected) < 0) {
    throw new IllegalStateException("DB " + actual + " older than required " + expected);
}

try {
    // startup with Hibernate
} catch (ConfigurationException e) {
    if (e.getMessage().contains("actual version is")) {
        log.error("Database older than build-time version: upgrade DB or rebuild with matching "
            + "quarkus.hibernate-orm.<pu>.database.version, or disable version-check explicitly");
    }
    throw e;
}

When it happens

Trigger: Deploying the app against a database whose version is lower than the one recorded at build time (quarkus.hibernate-orm.database.default or pu-level database.version), e.g. build-time assumed PostgreSQL 15 but runtime server is PostgreSQL 12; dialect's hardcoded minimum is also exceeded.

Common situations: Migrating deployments to older database servers (on-prem vs cloud); Dev Services at build time ran a newer DB than production; container image built against a newer DB and reused for an older environment; upgrading the Hibernate dialect while the DB stayed old.

Related errors

• Unable to find top command. Ensure you have a @CommandDefini
• The Hibernate ORM configuration in Quarkus does not support
• Datasource must be defined for persistence unit '%s'. Settin
• Could not guess the dialect from the database kind '${dbKind
• Unable to find file referenced in '<puPropertyKey(persistenc

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