quarkusio/quarkus · error · IllegalStateException

The Hibernate ORM configuration in Quarkus does not support

Error message

The Hibernate ORM configuration in Quarkus does not support sourcing configuration properties from resources named `hibernate.properties`, and this is now expressly prohibited as such a file could lead to unpredictable semantics. Please remove it from `${url}`

What it means

Quarkus configures Hibernate ORM through its own quarkus.hibernate-orm.* properties and does not read hibernate.properties; a hibernate.properties resource on the classpath could silently produce unpredictable semantics, so the build proactively fails with an IllegalStateException naming the resource URL.

Source

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

            beanValidationTraversableResolver
                    .produce(new BeanValidationTraversableResolverBuildItem(recorder.attributeLoadedPredicate()));
        }
    }

    private static Optional<JdbcDataSourceBuildItem> findDefaultDataSource(
            List<JdbcDataSourceBuildItem> jdbcDataSources) {
        return jdbcDataSources.stream()
                .filter(JdbcDataSourceBuildItem::isDefault)
                .findFirst();
    }

    private void validateHibernatePropertiesNotUsed() {
        try {
            final Enumeration<URL> resources = Thread.currentThread().getContextClassLoader().getResources(
                    "hibernate.properties");
            if (resources.hasMoreElements()) {
                final URL url = resources.nextElement();
                throw new IllegalStateException(
                        "The Hibernate ORM configuration in Quarkus does not support sourcing configuration properties from resources named `hibernate.properties`,"
                                + " and this is now expressly prohibited as such a file could lead to unpredictable semantics. Please remove it from `"
                                + url.toExternalForm() + '`');
            }
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }

    @BuildStep
    void handleNativeImageImportSql(BuildProducer<NativeImageResourceBuildItem> resources,
            List<PersistenceUnitDescriptorBuildItem> descriptors) {
        for (PersistenceUnitDescriptorBuildItem i : descriptors) {
            //add resources
            String resourceName = i.getExplicitSqlImportScriptResourceName();
            if (resourceName != null) {
                resources.produce(new NativeImageResourceBuildItem(resourceName));
            }

View on GitHub (pinned to e1c734241f)

Solutions

Delete hibernate.properties from src/main/resources and move needed settings into quarkus.hibernate-orm.* properties
If it comes from a dependency jar, exclude that resource/jar or override via quarkus.hibernate-orm.* settings after confirming no hibernate.properties remains

Example fix

// before: src/main/resources/hibernate.properties
hibernate.show_sql=true
// after: application.properties
quarkus.hibernate-orm.log.sql=true

Defensive patterns

Strategy: validation

Validate before calling

if (getClass().getResource("/hibernate.properties") != null) {
    throw new IllegalStateException("Remove hibernate.properties; use quarkus.hibernate-orm.*");
}

Prevention

Delete hibernate.properties from src/main/resources before migrating to Quarkus
Translate each hibernate.properties entry into its quarkus.hibernate-orm.* equivalent
Check dependency jars for bundled hibernate.properties (e.g. jar tf app.jar | grep hibernate.properties)

When it happens

Trigger: validateHibernatePropertiesNotUsed (called from the main build step) finds a classloader resource named 'hibernate.properties' via Thread.currentThread().getContextClassLoader().getResources().

Common situations: Migrating a plain Hibernate/Spring project that still ships hibernate.properties in src/main/resources; a transitive dependency bundling hibernate.properties in its jar.

Related errors

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