quarkusio/quarkus · error · ConfigurationException

Cannot use persistence.xml with Hibernate Reactive in Quarku

Error message

Cannot use persistence.xml with Hibernate Reactive in Quarkus. Must use application.properties instead.

What it means

Quarkus Hibernate Reactive does not support configuring persistence units via persistence.xml; all configuration must be in application.properties (quarkus.hibernate-orm.*). During deployment, if a persistence.xml is found whose provider is (or defaults to) the Hibernate Reactive provider, the build fails with this ConfigurationException.

Source

Thrown at extensions/hibernate-reactive/deployment/src/main/java/io/quarkus/hibernate/reactive/deployment/HibernateReactiveProcessor.java:124

            List<PersistenceUnitDefinitionBuildItem> persistenceUnitDefinitions,
            List<ReactiveDataSourceBuildItem> reactiveDataSources,
            ApplicationArchivesBuildItem applicationArchivesBuildItem,
            LaunchModeBuildItem launchMode,
            JpaModelPerPersistenceUnitBuildItem jpaModel,
            Capabilities capabilities,
            List<SqlLoadScriptDefaultBuildItem> additionalSqlLoadScriptDefaults,
            BuildProducer<NativeImageResourceBuildItem> nativeImageResources,
            BuildProducer<HotDeploymentWatchedFileBuildItem> hotDeploymentWatchedFiles,
            BuildProducer<PersistenceUnitDescriptorBuildItem> persistenceUnitDescriptors,
            BuildProducer<UnremovableBeanBuildItem> unremovableBeans,
            List<DatabaseKindDialectBuildItem> dbKindDialectBuildItems) {
        // Block any reactive persistence units from using persistence.xml
        for (PersistenceXmlDescriptorBuildItem persistenceXmlDescriptorBuildItem : persistenceXmlDescriptors) {
            String provider = persistenceXmlDescriptorBuildItem.getDescriptor().getProviderClassName();
            if (provider == null ||
                    provider.equals(FastBootHibernateReactivePersistenceProvider.class.getCanonicalName()) ||
                    provider.equals(FastBootHibernateReactivePersistenceProvider.IMPLEMENTATION_NAME)) {
                throw new ConfigurationException(
                        "Cannot use persistence.xml with Hibernate Reactive in Quarkus. Must use application.properties instead.");
            }
        }

        for (PersistenceUnitDefinitionBuildItem puDefinition : persistenceUnitDefinitions) {
            if (puDefinition.getParadigm() != ProgrammingParadigm.REACTIVE) {
                continue;
            }
            String puName = puDefinition.getPersistenceUnitName();
            var model = jpaModel.getModelPerPersistenceUnit().get(puName);
            if (model == null) {
                model = new JpaPersistenceUnitModel();
            }

            buildReactivePersistenceUnitFromConfig(hibernateOrmConfig, puDefinition, model,
                    reactiveDataSources,
                    applicationArchivesBuildItem,
                    launchMode,

View on GitHub (pinned to e1c734241f)

Solutions

1. Delete META-INF/persistence.xml and move all settings to quarkus.hibernate-orm.* properties in application.properties
2. If persistence.xml comes from a dependency, exclude that jar or the persistence.xml resource
3. Define named persistence units via quarkus.hibernate-orm."puname".* properties instead of persistence.xml elements
4. Keep reactive extensions (hibernate-reactive-panache) and remove hibernate-orm blocking deps if migrating

Example fix

// before (src/main/resources/META-INF/persistence.xml)
<persistence-unit name="default">
  <provider>io.quarkus.hibernate.reactive.runtime.FastBootHibernateReactivePersistenceProvider</provider>
</persistence-unit>

// after (application.properties)
quarkus.hibernate-orm.database.generation=update
quarkus.datasource.db-kind=postgresql

if (new File("src/main/resources/META-INF/persistence.xml").exists()) {
    throw new IllegalStateException("Remove persistence.xml; use quarkus.hibernate-orm.* properties");
}

try {
    quarkusApplication.start(); // build/deployment-time check
} catch (ConfigurationException e) {
    if (e.getMessage().contains("persistence.xml")) { migrateToProperties(); }
    throw e;
}

When it happens

Trigger: A META-INF/persistence.xml is present in the application, and its provider is null, equals FastBootHibernateReactivePersistenceProvider, or the Quarkus reactive provider canonical name, while Hibernate Reactive is used — detected in HibernateReactiveProcessor.buildReactivePersistenceUnitsFromConfig.

Common situations: Migrating a blocking Hibernate app (with persistence.xml) to Hibernate Reactive; reusing a shared persistence.xml inherited from dependencies; IDE scaffolding that generates persistence.xml; forgetting to remove persistence.xml after moving config to application.properties.

Related errors

• Reactive REST Data Panache does not work with 'quarkus-reste
• Failed to open path tree with root %s
• Dev services for ${request.getName()} requires a startable s
• Name cannot start with '/':${name}
• The class (${name}) cannot be created during deployment.

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