{"record":{"id":"f4e8e615799347f9","repo":"quarkusio/quarkus","slug":"when-using-offline-mode-with-quarkus-hibernate-or-f4e8e6","errorCode":null,"errorMessage":"When using offline mode with `quarkus.hibernate-orm.database.start-offline=true`, the schema management strategy `quarkus.hibernate-orm.schema-management.strategy` must be unset or set to `none`","messagePattern":"When using offline mode with `quarkus\\.hibernate-orm\\.database\\.start-offline=true`, the schema management strategy `quarkus\\.hibernate-orm\\.schema-management\\.strategy` must be unset or set to `none`","errorType":"exception","errorClass":"PersistenceException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-reactive/runtime/src/main/java/io/quarkus/hibernate/reactive/runtime/FastBootHibernateReactivePersistenceProvider.java","lineNumber":408,"sourceCode":"        }\n\n        serviceRegistry.addInitiator(new QuarkusReactiveConnectionPoolInitiator(pool));\n\n        InstanceHandle<Vertx> vertxHandle = Arc.container().instance(Vertx.class);\n        if (!vertxHandle.isAvailable()) {\n            throw new IllegalStateException(\"No Vert.x instance has been registered in ArC ?\");\n        }\n        serviceRegistry.addInitiator(new VertxInstanceInitiator(vertxHandle.get()));\n    }\n\n    private static void injectRuntimeConfiguration(HibernateOrmRuntimeConfigPersistenceUnit persistenceUnitConfig,\n            Builder runtimeSettingsBuilder) {\n\n        HibernateOrmRuntimeConfigPersistenceUnit.HibernateGenerationStrategy generationStrategy = persistenceUnitConfig\n                .schemaManagement().strategy();\n        if (!HibernateOrmRuntimeConfigPersistenceUnit.HibernateGenerationStrategy.NONE.equals(generationStrategy)\n                && persistenceUnitConfig.database().startOffline()) {\n            throw new PersistenceException(\n                    \"When using offline mode with `quarkus.hibernate-orm.database.start-offline=true`, the schema management strategy `quarkus.hibernate-orm.schema-management.strategy` must be unset or set to `none`\");\n        }\n\n        // Pass extraPhysicalTableTypes configuration\n        Optional<String> extraPhysicalTableTypes = persistenceUnitConfig.schemaManagement().extraPhysicalTableTypes();\n        if (extraPhysicalTableTypes.isPresent()) {\n            String extraTableTypesStr = extraPhysicalTableTypes.get();\n            runtimeSettingsBuilder.put(AvailableSettings.EXTRA_PHYSICAL_TABLE_TYPES, extraTableTypesStr);\n        }\n\n        // Database\n        runtimeSettingsBuilder.put(AvailableSettings.JAKARTA_HBM2DDL_DATABASE_ACTION,\n                getString(generationStrategy));\n\n        runtimeSettingsBuilder.put(AvailableSettings.JAKARTA_HBM2DDL_CREATE_SCHEMAS,\n                String.valueOf(persistenceUnitConfig.schemaManagement().createSchemas()));\n\n        if (persistenceUnitConfig.schemaManagement().haltOnError()) {","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-reactive/runtime/src/main/java/io/quarkus/hibernate/reactive/runtime/FastBootHibernateReactivePersistenceProvider.java#L390-L426","documentation":"Hibernate Reactive's offline mode lets an application start without a database connection at build/startup time, but in that mode schema management cannot be delegated to Hibernate at startup. If quarkus.hibernate-orm.database.start-offline=true and quarkus.hibernate-orm.schema-management.strategy is set to anything other than none, this PersistenceException is thrown to prevent contradictory configuration.","triggerScenarios":"Setting quarkus.hibernate-orm.database.start-offline=true together with quarkus.hibernate-orm.schema-management.strategy=drop-and-create (or create, drop, update, etc.) in application.properties, then starting the app via getEntityManagerFactoryBuilderOrNull -> injectRuntimeConfiguration.","commonSituations":"Copy-pasted schema strategy config combined with offline startup in containerized/Kubernetes deployments where the DB is unavailable at boot; leftover config from a non-offline setup; version migration where start-offline was newly enabled.","solutions":["Remove the quarkus.hibernate-orm.schema-management.strategy property (defaults to none)","Set quarkus.hibernate-orm.schema-management.strategy=none","If schema creation is needed, run it out-of-band (migration tool like Flyway/Liquibase) or disable start-offline by removing quarkus.hibernate-orm.database.start-offline=true"],"exampleFix":"// before (application.properties)\nquarkus.hibernate-orm.database.start-offline=true\nquarkus.hibernate-orm.schema-management.strategy=drop-and-create\n// after\nquarkus.hibernate-orm.database.start-offline=true\n# schema managed externally, e.g. via Flyway/Liquibase","handlingStrategy":"validation","validationCode":"// fail fast at startup before building the EMF\nvar cfg = ConfigProvider.getConfig();\nboolean offline = cfg.getOptionalValue(\"quarkus.hibernate-orm.database.start-offline\", Boolean.class).orElse(false);\nvar strategy = cfg.getOptionalValue(\"quarkus.hibernate-orm.schema-management.strategy\", String.class);\nif (offline && strategy.isPresent() && !\"none\".equalsIgnoreCase(strategy.get())) {\n    throw new IllegalStateException(\"start-offline=true requires schema-management.strategy=none\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    startApplication();\n} catch (PersistenceException e) {\n    if (e.getMessage().contains(\"start-offline\")) {\n        log.error(\"Offline mode conflicts with schema-management.strategy; unset it or set to none\");\n    }\n    throw e;\n}","preventionTips":["When enabling start-offline, audit all quarkus.hibernate-orm.schema-management.* properties","Manage schema with Flyway/Liquibase instead of Hibernate strategy in offline deployments","Validate config in CI with a startup smoke test for offline profile"],"tags":["quarkus","hibernate-reactive","configuration","offline-mode","schema-management"],"backgroundTag":"conflicting-configuration","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"}