{"record":{"id":"c1a67abd4781e00f","repo":"hibernate/hibernate-orm","slug":"convert-placed-on-embedded-attribute-must-define","errorCode":null,"errorMessage":"Convert placed on Embedded attribute must define (sub)attributeName","messagePattern":"Convert placed on Embedded attribute must define \\(sub\\)attributeName","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/ComponentPropertyHolder.java","lineNumber":204,"sourceCode":"\t *\n\t * @param embeddedMemberDetails The property that is the composite being described by this ComponentPropertyHolder\n\t */\n\tprivate Map<String,AttributeConversionInfo> processAttributeConversions(MemberDetails embeddedMemberDetails) {\n\t\tfinal Map<String,AttributeConversionInfo> infoMap = new HashMap<>();\n\n\t\tfinal var embeddableTypeDetails = embeddedMemberDetails.getType();\n\n\t\t// as a baseline, we want to apply conversions from the Embeddable and then overlay conversions\n\t\t// from the Embedded\n\n\t\t// first apply conversions from the Embeddable...\n\t\tprocessAttributeConversions( embeddableTypeDetails, infoMap );\n\n\t\t// then we can overlay any conversions from the Embedded attribute\n\t\tembeddedMemberDetails.forEachAnnotationUsage( Convert.class, getSourceModelContext(), (usage) -> {\n\t\t\tfinal var info = new AttributeConversionInfo( usage, embeddedMemberDetails );\n\t\t\tif ( isEmpty( info.getAttributeName() ) ) {\n\t\t\t\tthrow new IllegalStateException( \"Convert placed on Embedded attribute must define (sub)attributeName\" );\n\t\t\t}\n\t\t\tinfoMap.put( info.getAttributeName(), info );\n\t\t} );\n\n\t\treturn infoMap;\n\t}\n\n\tprivate void processAttributeConversions(TypeDetails embeddableTypeDetails, Map<String, AttributeConversionInfo> infoMap) {\n\t\tfinal var embeddableClassDetails = embeddableTypeDetails.determineRawClass();\n\t\tembeddableClassDetails.forEachAnnotationUsage( Convert.class, getSourceModelContext(), (usage) -> {\n\t\t\tfinal var info = new AttributeConversionInfo( usage, embeddableClassDetails );\n\t\t\tif ( isEmpty( info.getAttributeName() ) ) {\n\t\t\t\tthrow new IllegalStateException( \"@Convert placed on @Embeddable must define attributeName\" );\n\t\t\t}\n\t\t\tinfoMap.put( info.getAttributeName(), info );\n\t\t} );\n\t}\n","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/ComponentPropertyHolder.java#L186-L222","documentation":"Error \"Convert placed on Embedded attribute must define (sub)attributeName\" thrown in hibernate/hibernate-orm.","triggerScenarios":"A @Convert annotation lacks the attributeName needed to identify the converted attribute.","commonSituations":"@Convert on an @Embeddable or @Embedded attribute without (sub)attributeName, so the converter target is ambiguous.","solutions":["Set attributeName on the @Convert annotation to the (sub)attribute of the embedded attribute it applies to."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}