quarkusio/quarkus · error · PersistenceException

When using offline mode with `quarkus.hibernate-orm.database

Error message

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`

What it means

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.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/FastBootHibernatePersistenceProvider.java:503

        DataSource dataSource;
        try {
            // ClientProxy.unwrap is necessary to trigger exceptions on inactive datasources
            dataSource = ClientProxy.unwrap(AgroalDataSourceUtil.dataSourceInstance(dataSourceName).get());
        } catch (RuntimeException e) {
            throw PersistenceUnitUtil.unableToFindDataSource(persistenceUnitName, dataSourceName, e);
        }
        runtimeSettingsBuilder.put(AvailableSettings.DATASOURCE, dataSource);
    }

    private static void injectRuntimeConfiguration(HibernateOrmRuntimeConfigPersistenceUnit persistenceUnitConfig,
            Builder runtimeSettingsBuilder) {

        HibernateOrmRuntimeConfigPersistenceUnit.HibernateGenerationStrategy generationStrategy = persistenceUnitConfig
                .schemaManagement().strategy();
        if (!HibernateOrmRuntimeConfigPersistenceUnit.HibernateGenerationStrategy.NONE.equals(generationStrategy)
                && persistenceUnitConfig.database().startOffline()) {
            throw new PersistenceException(
                    "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`");
        }

        // Pass extraPhysicalTableTypes configuration
        Optional<String> extraPhysicalTableTypes = persistenceUnitConfig.schemaManagement().extraPhysicalTableTypes();
        if (extraPhysicalTableTypes.isPresent()) {
            String extraTableTypesStr = extraPhysicalTableTypes.get();
            runtimeSettingsBuilder.put(AvailableSettings.EXTRA_PHYSICAL_TABLE_TYPES, extraTableTypesStr);
        }

        runtimeSettingsBuilder.put(AvailableSettings.JAKARTA_HBM2DDL_DATABASE_ACTION,
                getString(generationStrategy));

        runtimeSettingsBuilder.put(AvailableSettings.JAKARTA_HBM2DDL_CREATE_SCHEMAS,
                String.valueOf(persistenceUnitConfig.schemaManagement().createSchemas()));

        if (persistenceUnitConfig.schemaManagement().haltOnError()) {
            runtimeSettingsBuilder.put(AvailableSettings.HBM2DDL_HALT_ON_ERROR, "true");

View on GitHub (pinned to e1c734241f)

Solutions

1. Set quarkus.hibernate-orm.schema-management.strategy=none (or remove the property) when start-offline=true.
2. Remove start-offline=true if you want schema management at startup.
3. Manage schema out-of-band (Flyway/Liquibase) while keeping offline mode.

Example fix

// before (application.properties)
quarkus.hibernate-orm.database.start-offline=true
quarkus.hibernate-orm.schema-management.strategy=update
// after
quarkus.hibernate-orm.database.start-offline=true
quarkus.hibernate-orm.schema-management.strategy=none

boolean offline = Boolean.getBoolean("quarkus.hibernate-orm.database.start-offline"); // resolve via ConfigProvider in-app
String strategy = System.getProperty("quarkus.hibernate-orm.schema-management.strategy", "");
if (offline && !strategy.isEmpty() && !strategy.equals("none")) {
    throw new IllegalArgumentException("start-offline=true requires schema-management.strategy=none");
}

When it happens

Trigger: 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.).

Common situations: 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.

Related errors

• Unable to find file referenced in '<puPropertyKey(persistenc
• The FastbootHibernateProvider PersistenceProvider can not su
• Hibernate ORM activated explicitly for persistence unit '<pu
• Unable to find an EntityManagerFactory for persistence unit
• Failed to load application configuration

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