{"record":{"id":"09ac3a35f689fc2d","repo":"hibernate/hibernate-orm","slug":"abstractdelegatingmetadatabuildingoptions-delegate","errorCode":null,"errorMessage":"AbstractDelegatingMetadataBuildingOptions delegate did not implement JpaOrmXmlPersistenceUnitDefaultAware; cannot delegate JpaOrmXmlPersistenceUnitDefaultAware#apply","messagePattern":"AbstractDelegatingMetadataBuildingOptions delegate did not implement JpaOrmXmlPersistenceUnitDefaultAware; cannot delegate JpaOrmXmlPersistenceUnitDefaultAware#apply","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingMetadataBuildingOptions.java","lineNumber":148,"sourceCode":"\t}\n\n\t@Override\n\tpublic boolean useNationalizedCharacterData() {\n\t\treturn delegate.useNationalizedCharacterData();\n\t}\n\n\t@Override\n\tpublic boolean isNoConstraintByDefault() {\n\t\treturn delegate.isNoConstraintByDefault();\n\t}\n\n\t@Override\n\tpublic void apply(JpaOrmXmlPersistenceUnitDefaults jpaOrmXmlPersistenceUnitDefaults) {\n\t\tif ( delegate instanceof JpaOrmXmlPersistenceUnitDefaultAware persistenceUnitDefaultAware ) {\n\t\t\tpersistenceUnitDefaultAware.apply( jpaOrmXmlPersistenceUnitDefaults );\n\t\t}\n\t\telse {\n\t\t\tthrow new HibernateException(\n\t\t\t\t\t\"AbstractDelegatingMetadataBuildingOptions delegate did not \" +\n\t\t\t\t\t\t\t\"implement JpaOrmXmlPersistenceUnitDefaultAware; \" +\n\t\t\t\t\t\t\t\"cannot delegate JpaOrmXmlPersistenceUnitDefaultAware#apply\"\n\t\t\t);\n\t\t}\n\t}\n\n\t@Override\n\tpublic void apply(PersistenceUnitMetadata persistenceUnitMetadata) {\n\t\tif ( delegate instanceof JpaOrmXmlPersistenceUnitDefaultAware persistenceUnitDefaultAware ) {\n\t\t\tpersistenceUnitDefaultAware.apply( persistenceUnitMetadata );\n\t\t}\n\t\telse {\n\t\t\tthrow new HibernateException(\n\t\t\t\t\t\"AbstractDelegatingMetadataBuildingOptions delegate did not \" +\n\t\t\t\t\t\t\t\"implement JpaOrmXmlPersistenceUnitDefaultAware; \" +\n\t\t\t\t\t\t\t\"cannot delegate JpaOrmXmlPersistenceUnitDefaultAware#apply\"\n\t\t\t);","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingMetadataBuildingOptions.java#L130-L166","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make your custom MetadataBuildingOptions delegate implement org.hibernate.boot.spi.JpaOrmXmlPersistenceUnitDefaultAware (apply(JpaOrmXmlPersistenceUnitDefaults) and apply(PersistenceUnitMetadata)).","Or override apply(JpaOrmXmlPersistenceUnitDefaults) in your AbstractDelegatingMetadataBuildingOptions subclass to store the defaults yourself instead of delegating.","Model your implementation on Hibernate's own MetadataBuildingOptionsImpl, which implements both aware interfaces.","If you do not need custom options, unwrap: pass Hibernate's options object directly so the instanceof check succeeds."],"exampleFix":"// before\nclass MyOptions implements MetadataBuildingOptions { ... } // no JpaOrmXmlPersistenceUnitDefaultAware\nnew AbstractDelegatingMetadataBuildingOptions( new MyOptions() ) { } // throws on orm.xml defaults\n\n// after\nclass MyOptions implements MetadataBuildingOptions, JpaOrmXmlPersistenceUnitDefaultAware {\n    @Override\n    public void apply(JpaOrmXmlPersistenceUnitDefaults defaults) { this.defaults = defaults; }\n    @Override\n    public void apply(PersistenceUnitMetadata metadata) { /* ... */ }\n}","handlingStrategy":"type-guard","validationCode":"MetadataBuildingOptions delegate = /* your custom options */ myOptions;\nif ( !( delegate instanceof org.hibernate.boot.spi.JpaOrmXmlPersistenceUnitDefaultAware ) ) {\n    throw new IllegalStateException(\n            \"delegate must implement JpaOrmXmlPersistenceUnitDefaultAware to receive orm.xml persistence-unit-defaults\" );\n}","typeGuard":"static boolean receivesJpaDefaults(MetadataBuildingOptions options) {\n    return options instanceof org.hibernate.boot.spi.JpaOrmXmlPersistenceUnitDefaultAware;\n}","tryCatchPattern":null,"preventionTips":["When implementing Hibernate SPI wrappers, mirror Hibernate's own implementations (MetadataBuildingOptionsImpl) and implement every aware interface of the version you target.","Recompile SPI integrations against each new Hibernate release - added interface methods/aware contracts surface at compile time.","Run an integration test that bootstraps with an orm.xml containing <persistence-unit-defaults> to exercise the delegation path."],"tags":["hibernate","spi","bootstrap","metadata","orm-xml"],"backgroundTag":"spi-delegate-contract-violation","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}