{"record":{"id":"647aa6a214f72659","repo":"quarkusio/quarkus","slug":"persistence-unit-persistenceunitname-was-confi","errorCode":null,"errorMessage":"Persistence unit '' was configured to run with a database version of at least ''[, (Quarkus default)], but the actual version is ''. Consider upgrading your database. [ The minimum version supported by the dialect is .] [ Alternatively, rebuild your application with '=' (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 '=false'.]","messagePattern":"Persistence unit '' was configured to run with a database version of at least ''\\[, \\(Quarkus default\\)\\], but the actual version is ''\\. Consider upgrading your database\\. \\[ The minimum version supported by the dialect is \\.\\] \\[ Alternatively, rebuild your application with '=' \\(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 '=false'\\.\\]","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/service/QuarkusRuntimeInitDialectFactory.java","lineNumber":128,"sourceCode":" // but just let's be safe...\n if (datasourceName.isPresent()) {\n errorMessage.append(String.format(Locale.ROOT,\n \" Alternatively, rebuild your application with\"\n + \" '%1$s=%2$s'\"\n + \" (but this may disable some features and/or impact performance negatively).\",\n isFromPersistenceXml ? AvailableSettings.JAKARTA_HBM2DDL_DB_VERSION\n : DataSourceUtil.dataSourcePropertyKey(datasourceName.get(), \"db-version\"),\n DialectVersions.toString(actualDbVersion.get())));\n }\n if (!isFromPersistenceXml) {\n errorMessage.append(String.format(Locale.ROOT,\n \" As a last resort,\"\n + \" if you are certain your application will work correctly even though the database version is incorrect,\"\n + \" disable the check with\"\n + \" '%1$s=false'.\",\n HibernateOrmRuntimeConfig.puPropertyKey(persistenceUnitName, \"database.version-check.enabled\")));\n }\n throw new ConfigurationException(errorMessage.toString());\n }\n }\n\n private Optional retrieveDbVersion(DialectResolutionInfoSource resolutionInfoSource) {\n try {\n var resolutionInfo = resolutionInfoSource == null ? null\n // This may throw an exception if the DB cannot be reached, in particular with Hibernate Reactive.\n : resolutionInfoSource.getDialectResolutionInfo();\n if (resolutionInfo == null) {\n return Optional.empty();\n }\n triedToRetrieveDbVersion = true;\n return Optional.of(dialect.determineDatabaseVersion(resolutionInfo));\n } catch (RuntimeException e) {\n LOG.warnf(e, \"Persistence unit %1$s: Could not retrieve the database version to check it is at least %2$s\",\n persistenceUnitName, buildTimeDbVersion);\n return Optional.empty();\n }","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/service/QuarkusRuntimeInitDialectFactory.java#L110-L146","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade the database server to at least the recorded/minimum version (preferred, keeps all features and optimizations).","Rebuild the application with quarkus.hibernate-orm..database.version= (or database.default) so the dialect targets the actual server.","If you are certain your SQL works on the older DB, disable the check with quarkus.hibernate-orm..database.version-check.enabled=false — accepting possible disabled features/perf impact."],"exampleFix":"// before (built against newer DB, deployed to PostgreSQL 12)\n# quarkus.hibernate-orm.database.version=15\n\n// after\nquarkus.hibernate-orm.database.version=12\n# or explicitly:\n# quarkus.hibernate-orm.database.version-check.enabled=false","handlingStrategy":"validation","validationCode":"// Compare actual DB version against expected before deploying\nString expected = config.getValue(\"quarkus.hibernate-orm.database.version\", String.class);\nString actual = queryDbVersion(); // e.g. \"select version()\"\nif (expected != null && versionCompare(actual, expected) < 0) {\n throw new IllegalStateException(\"DB \" + actual + \" older than required \" + expected);\n}","typeGuard":null,"tryCatchPattern":"try {\n // startup with Hibernate\n} catch (ConfigurationException e) {\n if (e.getMessage().contains(\"actual version is\")) {\n log.error(\"Database older than build-time version: upgrade DB or rebuild with matching \"\n + \"quarkus.hibernate-orm..database.version, or disable version-check explicitly\");\n }\n throw e;\n}","preventionTips":["Pin the same database version in build, dev (Dev Services) and production environments","Record quarkus.hibernate-orm.database.version matching your oldest production DB","Verify production DB version in deployment checks before app start","Only disable version-check.enabled as a conscious last resort"],"tags":["hibernate-orm","database-version","dialect","startup","configuration"],"backgroundTag":"database-version-mismatch","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}