{"record":{"id":"e54bab04ee858a5b","repo":"quarkusio/quarkus","slug":"when-using-offline-mode-with-quarkus-hibernate-or","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-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/FastBootHibernatePersistenceProvider.java","lineNumber":503,"sourceCode":"\n        DataSource dataSource;\n        try {\n            // ClientProxy.unwrap is necessary to trigger exceptions on inactive datasources\n            dataSource = ClientProxy.unwrap(AgroalDataSourceUtil.dataSourceInstance(dataSourceName).get());\n        } catch (RuntimeException e) {\n            throw PersistenceUnitUtil.unableToFindDataSource(persistenceUnitName, dataSourceName, e);\n        }\n        runtimeSettingsBuilder.put(AvailableSettings.DATASOURCE, dataSource);\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        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()) {\n            runtimeSettingsBuilder.put(AvailableSettings.HBM2DDL_HALT_ON_ERROR, \"true\");","sourceCodeStart":485,"sourceCodeEnd":521,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/FastBootHibernatePersistenceProvider.java#L485-L521","documentation":"In offline mode (quarkus.hibernate-orm.database.start-offline=true) the database is unreachable at startup, so no schema management may run. injectRuntimeConfiguration (called from buildRuntimeSettings) validates that schema-management.strategy is NONE and throws PersistenceException otherwise.","triggerScenarios":"quarkus.hibernate-orm.database.start-offline=true combined with quarkus.hibernate-orm.schema-management.strategy set to anything other than none (create, drop-and-create, update, validate, etc.).","commonSituations":"Enabling offline startup for Kubernetes/containers while leaving a previously set strategy; copying config from a non-offline project; toggling start-offline in an environment profile without cleaning up the strategy property.","solutions":["Set quarkus.hibernate-orm.schema-management.strategy=none (or remove the property) when start-offline=true.","Remove start-offline=true if you want schema management at startup.","Manage schema out-of-band (Flyway/Liquibase) while keeping offline mode."],"exampleFix":"// before (application.properties)\nquarkus.hibernate-orm.database.start-offline=true\nquarkus.hibernate-orm.schema-management.strategy=update\n// after\nquarkus.hibernate-orm.database.start-offline=true\nquarkus.hibernate-orm.schema-management.strategy=none","handlingStrategy":"validation","validationCode":"boolean offline = Boolean.getBoolean(\"quarkus.hibernate-orm.database.start-offline\"); // resolve via ConfigProvider in-app\nString strategy = System.getProperty(\"quarkus.hibernate-orm.schema-management.strategy\", \"\");\nif (offline && !strategy.isEmpty() && !strategy.equals(\"none\")) {\n    throw new IllegalArgumentException(\"start-offline=true requires schema-management.strategy=none\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Whenever you set start-offline=true, audit schema-management.strategy in every profile.","Prefer Flyway/Liquibase for schema management in offline deployments.","Remove stale schema strategy properties when adopting offline mode."],"tags":["quarkus","hibernate-orm","configuration","offline","schema"],"backgroundTag":"offline-mode-schema-conflict","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"}