quarkusio/quarkus · error · PersistenceException

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

Error message

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`

What it means

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.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/service/QuarkusRuntimeInitDialectFactoryInitiator.java:43

    private final boolean versionCheckEnabled;
    private final boolean startOffline;

    public QuarkusRuntimeInitDialectFactoryInitiator(String persistenceUnitName,
            boolean isFromPersistenceXml, Dialect dialect,
            RecordedConfig recordedConfig,
            HibernateOrmRuntimeConfigPersistenceUnit runtimePuConfig) {
        this.persistenceUnitName = persistenceUnitName;
        this.isFromPersistenceXml = isFromPersistenceXml;
        this.dialect = dialect;
        this.datasourceName = recordedConfig.getDataSource();
        // We set the version from the dialect since it can be overridden from persistence.xml or unsupported config
        this.buildTimeDbVersion = dialect.getVersion();
        this.dbVersionUserSpecified = recordedConfig.isDbVersionUserSpecified();
        HibernateOrmRuntimeConfigPersistenceUnit.HibernateOrmConfigPersistenceUnitDatabase database = runtimePuConfig
                .database();

        if (database.startOffline() && database.versionCheckEnabled().filter(v -> v.booleanValue()).isPresent()) {
            throw new PersistenceException(
                    "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`");
        }

        this.startOffline = database.startOffline();
        this.versionCheckEnabled = runtimePuConfig.database().versionCheckEnabled()
                .orElse(!startOffline);
    }

    @Override
    public Class<DialectFactory> getServiceInitiated() {
        return DialectFactory.class;
    }

    @Override
    public DialectFactory initiateService(Map<String, Object> configurationValues, ServiceRegistryImplementor registry) {
        return new QuarkusRuntimeInitDialectFactory(persistenceUnitName, isFromPersistenceXml, dialect, datasourceName,
                buildTimeDbVersion, dbVersionUserSpecified, versionCheckEnabled, startOffline);
    }

View on GitHub (pinned to e1c734241f)

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.

Example fix

// before
quarkus.hibernate-orm.database.start-offline=true
quarkus.hibernate-orm.database.version-check.enabled=true

// after
quarkus.hibernate-orm.database.start-offline=true
# version check must be unset or false
quarkus.hibernate-orm.database.version-check.enabled=false

Defensive patterns

Strategy: validation

Validate before calling

boolean startOffline = config.getValue("quarkus.hibernate-orm.database.start-offline", Boolean.class, false);
Optional<Boolean> vCheck = config.getOptionalValue("quarkus.hibernate-orm.database.version-check.enabled", Boolean.class);
if (startOffline && vCheck.isPresent() && vCheck.get()) {
    throw new IllegalStateException("start-offline=true requires version-check.enabled unset or false");
}

Prevention

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

When it happens

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

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

Related errors

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