hibernate/hibernate-orm · error · HibernateException

AbstractDelegatingMetadataBuildingOptions delegate did not i

Error message

AbstractDelegatingMetadataBuildingOptions delegate did not implement JpaOrmXmlPersistenceUnitDefaultAware; cannot delegate JpaOrmXmlPersistenceUnitDefaultAware#apply

What it means

AbstractDelegatingMetadataBuildingOptions is a convenience SPI wrapper: every method forwards to the wrapped 'delegate'. apply(JpaOrmXmlPersistenceUnitDefaults) can only forward if the delegate implements JpaOrmXmlPersistenceUnitDefaultAware; since that method exists solely to feed orm.xml <persistence-unit-defaults> into the options, a delegate lacking the interface makes delegation impossible and Hibernate throws instead of silently dropping the defaults.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingMetadataBuildingOptions.java:148

	}

	@Override
	public boolean useNationalizedCharacterData() {
		return delegate.useNationalizedCharacterData();
	}

	@Override
	public boolean isNoConstraintByDefault() {
		return delegate.isNoConstraintByDefault();
	}

	@Override
	public void apply(JpaOrmXmlPersistenceUnitDefaults jpaOrmXmlPersistenceUnitDefaults) {
		if ( delegate instanceof JpaOrmXmlPersistenceUnitDefaultAware persistenceUnitDefaultAware ) {
			persistenceUnitDefaultAware.apply( jpaOrmXmlPersistenceUnitDefaults );
		}
		else {
			throw new HibernateException(
					"AbstractDelegatingMetadataBuildingOptions delegate did not " +
							"implement JpaOrmXmlPersistenceUnitDefaultAware; " +
							"cannot delegate JpaOrmXmlPersistenceUnitDefaultAware#apply"
			);
		}
	}

	@Override
	public void apply(PersistenceUnitMetadata persistenceUnitMetadata) {
		if ( delegate instanceof JpaOrmXmlPersistenceUnitDefaultAware persistenceUnitDefaultAware ) {
			persistenceUnitDefaultAware.apply( persistenceUnitMetadata );
		}
		else {
			throw new HibernateException(
					"AbstractDelegatingMetadataBuildingOptions delegate did not " +
							"implement JpaOrmXmlPersistenceUnitDefaultAware; " +
							"cannot delegate JpaOrmXmlPersistenceUnitDefaultAware#apply"
			);

View on GitHub (pinned to fad1729dce)

Solutions

1. Make your custom MetadataBuildingOptions delegate implement org.hibernate.boot.spi.JpaOrmXmlPersistenceUnitDefaultAware (apply(JpaOrmXmlPersistenceUnitDefaults) and apply(PersistenceUnitMetadata)).
2. Or override apply(JpaOrmXmlPersistenceUnitDefaults) in your AbstractDelegatingMetadataBuildingOptions subclass to store the defaults yourself instead of delegating.
3. Model your implementation on Hibernate's own MetadataBuildingOptionsImpl, which implements both aware interfaces.
4. If you do not need custom options, unwrap: pass Hibernate's options object directly so the instanceof check succeeds.

Example fix

// before
class MyOptions implements MetadataBuildingOptions { ... } // no JpaOrmXmlPersistenceUnitDefaultAware
new AbstractDelegatingMetadataBuildingOptions( new MyOptions() ) { } // throws on orm.xml defaults

// after
class MyOptions implements MetadataBuildingOptions, JpaOrmXmlPersistenceUnitDefaultAware {
    @Override
    public void apply(JpaOrmXmlPersistenceUnitDefaults defaults) { this.defaults = defaults; }
    @Override
    public void apply(PersistenceUnitMetadata metadata) { /* ... */ }
}

MetadataBuildingOptions delegate = /* your custom options */ myOptions;
if ( !( delegate instanceof org.hibernate.boot.spi.JpaOrmXmlPersistenceUnitDefaultAware ) ) {
    throw new IllegalStateException(
            "delegate must implement JpaOrmXmlPersistenceUnitDefaultAware to receive orm.xml persistence-unit-defaults" );
}

static boolean receivesJpaDefaults(MetadataBuildingOptions options) {
    return options instanceof org.hibernate.boot.spi.JpaOrmXmlPersistenceUnitDefaultAware;
}

When it happens

Trigger: Bootstrapping with a custom MetadataBuildingOptions implementation that is wrapped in AbstractDelegatingMetadataBuildingOptions but does not implement JpaOrmXmlPersistenceUnitDefaultAware, while an orm.xml with <persistence-unit-defaults> (schema/catalog/delimited-identifiers/cascade-persist defaults) is processed.

Common situations: Integrations or frameworks (custom bootstrappers, test harnesses) that supply their own MetadataBuildingOptions and later add orm.xml mappings; copying an old custom options implementation to a newer Hibernate where JpaOrmXmlPersistenceUnitDefaultAware was added to the contract.

Related errors

• #buildNamedQueryRepository should not be called on InFlightM
• You should not be building a SessionFactory from an in-fligh
• Named query definition name is null: %s
• Named native query definition name is null: {}
• Result-set mapping name is null: {}

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/09ac3a35f689fc2d. Report an issue: GitHub.