{"record":{"id":"ee22597d40f00e89","repo":"quarkusio/quarkus","slug":"when-using-offline-mode-quarkus-hibernate-orm-dat","errorCode":null,"errorMessage":"When using offline mode `quarkus.hibernate-orm.database.start-offline=true`, version check `quarkus.hibernate-orm.database.version-check.enabled` must be unset or set to `false`","messagePattern":"When using offline mode `quarkus\\.hibernate-orm\\.database\\.start-offline=true`, version check `quarkus\\.hibernate-orm\\.database\\.version-check\\.enabled` must be unset or set to `false`","errorType":"exception","errorClass":"PersistenceException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/service/QuarkusRuntimeInitDialectFactoryInitiator.java","lineNumber":43,"sourceCode":"    private final boolean versionCheckEnabled;\n    private final boolean startOffline;\n\n    public QuarkusRuntimeInitDialectFactoryInitiator(String persistenceUnitName,\n            boolean isFromPersistenceXml, Dialect dialect,\n            RecordedConfig recordedConfig,\n            HibernateOrmRuntimeConfigPersistenceUnit runtimePuConfig) {\n        this.persistenceUnitName = persistenceUnitName;\n        this.isFromPersistenceXml = isFromPersistenceXml;\n        this.dialect = dialect;\n        this.datasourceName = recordedConfig.getDataSource();\n        // We set the version from the dialect since it can be overridden from persistence.xml or unsupported config\n        this.buildTimeDbVersion = dialect.getVersion();\n        this.dbVersionUserSpecified = recordedConfig.isDbVersionUserSpecified();\n        HibernateOrmRuntimeConfigPersistenceUnit.HibernateOrmConfigPersistenceUnitDatabase database = runtimePuConfig\n                .database();\n\n        if (database.startOffline() && database.versionCheckEnabled().filter(v -> v.booleanValue()).isPresent()) {\n            throw new PersistenceException(\n                    \"When using offline mode `quarkus.hibernate-orm.database.start-offline=true`, version check `quarkus.hibernate-orm.database.version-check.enabled` must be unset or set to `false`\");\n        }\n\n        this.startOffline = database.startOffline();\n        this.versionCheckEnabled = runtimePuConfig.database().versionCheckEnabled()\n                .orElse(!startOffline);\n    }\n\n    @Override\n    public Class<DialectFactory> getServiceInitiated() {\n        return DialectFactory.class;\n    }\n\n    @Override\n    public DialectFactory initiateService(Map<String, Object> configurationValues, ServiceRegistryImplementor registry) {\n        return new QuarkusRuntimeInitDialectFactory(persistenceUnitName, isFromPersistenceXml, dialect, datasourceName,\n                buildTimeDbVersion, dbVersionUserSpecified, versionCheckEnabled, startOffline);\n    }","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/service/QuarkusRuntimeInitDialectFactoryInitiator.java#L25-L61","documentation":"QuarkusRuntimeInitDialectFactoryInitiator's constructor validates configuration consistency: offline mode (quarkus.hibernate-orm.database.start-offline=true) means no database connection exists at startup, so Hibernate's runtime version check (database.version-check.enabled) cannot run. If version check is explicitly enabled together with offline mode, it throws PersistenceException at persistence unit initialization.","triggerScenarios":"Setting both quarkus.hibernate-orm.database.start-offline=true and quarkus.hibernate-orm.database.version-check.enabled=true (explicitly, not defaulted) for the same persistence unit; the check uses versionCheckEnabled().filter(v -> v.booleanValue()).isPresent(), so only an explicit true triggers it.","commonSituations":"Building apps for environments where the DB may be absent at startup (Kubernetes init, CLI tools, native images connecting later) while keeping an old explicit version-check=true from previous config; copying config between persistence units.","solutions":["Remove quarkus.hibernate-orm.database.version-check.enabled or set it to false when start-offline=true.","Keep only start-offline=true; Quarkus defaults version check to off when offline (orElse(!startOffline)).","If you actually need version checking, remove start-offline so the app connects to the DB at startup."],"exampleFix":"// before\nquarkus.hibernate-orm.database.start-offline=true\nquarkus.hibernate-orm.database.version-check.enabled=true\n\n// after\nquarkus.hibernate-orm.database.start-offline=true\n# version check must be unset or false\nquarkus.hibernate-orm.database.version-check.enabled=false","handlingStrategy":"validation","validationCode":"boolean startOffline = config.getValue(\"quarkus.hibernate-orm.database.start-offline\", Boolean.class, false);\nOptional<Boolean> vCheck = config.getOptionalValue(\"quarkus.hibernate-orm.database.version-check.enabled\", Boolean.class);\nif (startOffline && vCheck.isPresent() && vCheck.get()) {\n    throw new IllegalStateException(\"start-offline=true requires version-check.enabled unset or false\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When enabling start-offline, remove any explicit version-check.enabled=true","Audit per-persistence-unit config: the check applies to each PU's database() section","Remember offline mode defaults version check to false — no need to set it explicitly"],"tags":["hibernate-orm","offline-mode","version-check","configuration"],"backgroundTag":"incompatible-config-combination","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}