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

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.

Source

Thrown at extensions/hibernate-reactive/runtime/src/main/java/io/quarkus/hibernate/reactive/runtime/FastBootHibernateReactivePersistenceProvider.java:408

        }

        serviceRegistry.addInitiator(new QuarkusReactiveConnectionPoolInitiator(pool));

        InstanceHandle<Vertx> vertxHandle = Arc.container().instance(Vertx.class);
        if (!vertxHandle.isAvailable()) {
            throw new IllegalStateException("No Vert.x instance has been registered in ArC ?");
        }
        serviceRegistry.addInitiator(new VertxInstanceInitiator(vertxHandle.get()));
    }

    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);
        }

        // Database
        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()) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove the quarkus.hibernate-orm.schema-management.strategy property (defaults to none)
2. Set quarkus.hibernate-orm.schema-management.strategy=none
3. 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

Example fix

// before (application.properties)
quarkus.hibernate-orm.database.start-offline=true
quarkus.hibernate-orm.schema-management.strategy=drop-and-create
// after
quarkus.hibernate-orm.database.start-offline=true
# schema managed externally, e.g. via Flyway/Liquibase

// fail fast at startup before building the EMF
var cfg = ConfigProvider.getConfig();
boolean offline = cfg.getOptionalValue("quarkus.hibernate-orm.database.start-offline", Boolean.class).orElse(false);
var strategy = cfg.getOptionalValue("quarkus.hibernate-orm.schema-management.strategy", String.class);
if (offline && strategy.isPresent() && !"none".equalsIgnoreCase(strategy.get())) {
    throw new IllegalStateException("start-offline=true requires schema-management.strategy=none");
}

try {
    startApplication();
} catch (PersistenceException e) {
    if (e.getMessage().contains("start-offline")) {
        log.error("Offline mode conflicts with schema-management.strategy; unset it or set to none");
    }
    throw e;
}

When it happens

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

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

Related errors

• Failed to load application configuration
• Failed to initialize application configuration
• Unrecognized option for quarkus.bootstrap.misaligned-platfor
• The configuration ${clazz} is missing the @ConfigRoot annota
• The configuration ${clazz} is missing the @ConfigMapping ann

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