quarkusio/quarkus · error · ConfigurationException

A legacy persistence.xml file is present in the classpath, b

Error message

A legacy persistence.xml file is present in the classpath, but Hibernate ORM is also configured through the Quarkus config file.
Legacy persistence.xml files and Quarkus configuration cannot be used at the same time.
To ignore persistence.xml files, set the configuration property 'quarkus.hibernate-orm.persistence-xml.ignore' to 'true'.
To use persistence.xml files, remove all 'quarkus.hibernate-orm*' properties from the Quarkus config file.

What it means

Quarkus supports configuring Hibernate ORM either through a legacy META-INF/persistence.xml or through quarkus.hibernate-orm.* configuration properties, but never both at once. If a persistence.xml is on the classpath and any non-persistence-xml quarkus.hibernate-orm property is set, contributeQuarkusConfigToJpaModel throws a ConfigurationException explaining the two remediation paths.

Source

Thrown at extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmProcessor.java:553

        // so that those classes are indexed, bytecode-enhanced, registered for reflection and assigned to their
        // persistence unit without the contributing extension having to produce a separate AdditionalJpaModelBuildItem.
        for (AdditionalPersistenceUnitBuildItem additionalPersistenceUnit : additionalPersistenceUnits) {
            Set<String> persistenceUnits = Set.of(additionalPersistenceUnit.getPersistenceUnitName());
            for (String className : additionalPersistenceUnit.getManagedClassNames()) {
                additionalJpaModel.produce(new AdditionalJpaModelBuildItem(className, persistenceUnits));
            }
        }
    }

    @BuildStep
    public void contributeQuarkusConfigToJpaModel(
            BuildProducer<JpaModelPersistenceUnitContributionBuildItem> jpaModelPuContributions,
            HibernateOrmConfig hibernateOrmConfig, List<PersistenceXmlDescriptorBuildItem> persistenceXmlDescriptors) {
        // TODO move this validation to a dedicated method, preferably very early in the build?
        //   See also a conceptually similar check in buildBlockingPersistenceUnitFromPersistenceXml
        if (!persistenceXmlDescriptors.isEmpty()) {
            if (hibernateOrmConfig.isAnyNonPersistenceXmlPropertySet()) {
                throw new ConfigurationException(
                        "A legacy persistence.xml file is present in the classpath, but Hibernate ORM is also configured through the Quarkus config file.\n"
                                + "Legacy persistence.xml files and Quarkus configuration cannot be used at the same time.\n"
                                + "To ignore persistence.xml files, set the configuration property"
                                + " 'quarkus.hibernate-orm.persistence-xml.ignore' to 'true'.\n"
                                + "To use persistence.xml files, remove all '" + HIBERNATE_ORM_CONFIG_PREFIX
                                + "*' properties from the Quarkus config file.");
            } else {
                // It's theoretically possible to use the Quarkus Hibernate ORM extension
                // without setting any build-time configuration property,
                // so the condition above might not catch all attempts to use persistence.xml and Quarkus-configured PUs
                // at the same time.
                // At that point, the only thing we can do is log something,
                // so that hopefully people in that situation will notice that their Quarkus configuration is being ignored.
                LOG.infof(
                        "A legacy persistence.xml file is present in the classpath. This file will be used to configure JPA/Hibernate ORM persistence units,"
                                + " and any configuration of the Hibernate ORM extension will be ignored."
                                + " To ignore persistence.xml files instead, set the configuration property"
                                + " 'quarkus.hibernate-orm.persistence-xml.ignore' to 'true'.");

View on GitHub (pinned to e1c734241f)

Solutions

  1. Set quarkus.hibernate-orm.persistence-xml.ignore=true to ignore the persistence.xml and keep Quarkus config
  2. Delete META-INF/persistence.xml and configure everything via quarkus.hibernate-orm.* properties
  3. Remove all quarkus.hibernate-orm* properties to use only the persistence.xml

Example fix

// application.properties
// before
quarkus.hibernate-orm.datasource.name=myds
// after (choose one)
quarkus.hibernate-orm.persistence-xml.ignore=true
quarkus.hibernate-orm.datasource.name=myds
# ...and delete META-INF/persistence.xml
Defensive patterns

Strategy: validation

Validate before calling

boolean hasPersistenceXml = getClass().getResource("/META-INF/persistence.xml") != null;
boolean hasQuarkusOrmProps = configContainsPrefix("quarkus.hibernate-orm.");
if (hasPersistenceXml && hasQuarkusOrmProps
    && !configContains("quarkus.hibernate-orm.persistence-xml.ignore=true")) {
    throw new IllegalStateException("Choose either persistence.xml or quarkus.hibernate-orm.* config");
}

Prevention

When it happens

Trigger: A META-INF/persistence.xml descriptor is present AND hibernateOrmConfig.isAnyNonPersistenceXmlPropertySet() is true (any quarkus.hibernate-orm* property other than quarkus.hibernate-orm.persistence-xml.ignore is set in application config).

Common situations: Migrating a classic Java EE app that keeps persistence.xml while also adding quarkus.hibernate-orm.datasource or dialect settings; leaving a leftover persistence.xml in test resources while the app uses Quarkus config.

Related errors

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