{"record":{"id":"24cb81c8e3ab2b1b","repo":"hibernate/hibernate-orm","slug":"targetembeddable-can-only-be-specified-on-propert","errorCode":null,"errorMessage":"@TargetEmbeddable can only be specified on properties marked with @Embedded or @ElementCollection [%s$%s]","messagePattern":"@TargetEmbeddable can only be specified on properties marked with @Embedded or @ElementCollection \\[(.+?)\\$(.+?)\\]","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/PropertyInferredData.java","lineNumber":117,"sourceCode":"\t\tif ( targetEmbeddable != null ) {\n\t\t\treturn resolveTargetEmbeddableAnnotation( targetEmbeddable, sourceModelContext );\n\t\t}\n\n\t\treturn propertyMember.resolveRelativeType( ownerType );\n\t}\n\n\tprivate static TargetEmbeddable getTargetEmbeddableAnnotation(MemberDetails memberDetails) {\n\t\t// first we look for the annotation on the member itself\n\t\tfinal var memberAnnotation = memberDetails.getDirectAnnotationUsage( TargetEmbeddable.class );\n\t\tif ( memberAnnotation != null ) {\n\t\t\t// this should only be allowed for embedded or collections-of-embeddables.\n\t\t\t// \t\tNOTE: this is tricky to check for collections-of-embeddables as it\n\t\t\t// \t\twould require a deep check of the collection's component type, so\n\t\t\t// \t\tfor now just assume the mapping is correct if we find @ElementCollection\n\t\t\tfinal boolean allowed = memberDetails.hasDirectAnnotationUsage( Embedded.class )\n\t\t\t\t\t|| memberDetails.hasDirectAnnotationUsage( ElementCollection.class );\n\t\t\tif ( !allowed ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\tString.format(\n\t\t\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\t\t\"@TargetEmbeddable can only be specified on properties marked with @Embedded or @ElementCollection [%s$%s]\",\n\t\t\t\t\t\t\t\tmemberDetails.getDeclaringType().getName(),\n\t\t\t\t\t\t\t\tmemberDetails.getName()\n\t\t\t\t\t\t)\n\t\t\t\t);\n\t\t\t}\n\n\t\t\treturn memberAnnotation;\n\t\t}\n\n\t\t// then, look on the member's type\n\t\t// \t\tNOTE: this is not supported for collections-of-embeddables\n\t\t// \t\tfor the same reason stated above\n\t\tClassDetails memberRawClass = memberDetails.getAssociatedType().determineRawClass();\n\t\tif (memberRawClass.isJdkClass()) {\n\t\t\treturn null;","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/PropertyInferredData.java#L99-L135","documentation":"@TargetEmbeddable names the embeddable implementation for an attribute; PropertyInferredData.getTargetEmbeddableAnnotation accepts it only when the member itself also carries @Embedded or @ElementCollection (a @ElementCollection member is trusted without deep-checking its component type). Anything else — association, plain field, meta-annotated member — throws a MappingException formatted as declaringType$memberName during property inference.","triggerScenarios":"Placing @TargetEmbeddable(Address.class) on a @ManyToOne, @OneToOne without @Embedded, a @OneToMany collection of embeddables (not @ElementCollection), or a plain unannotated field. Thrown while Hibernate infers the property type from the member during binding.","commonSituations":"Confusing @TargetEmbeddable with org.hibernate.annotations.@Target (the latter is for entity association targets); annotating @OneToMany List<Line> with @TargetEmbeddable instead of @ElementCollection; copying the annotation to an association when refactoring an embeddable into an entity.","solutions":["If the target really is an embeddable value, annotate the attribute @Embedded (single) or @ElementCollection (collection) alongside @TargetEmbeddable.","If the target is an entity, remove @TargetEmbeddable and use @ManyToOne/@OneToOne with org.hibernate.annotations.@Target if you must pin the class.","If the collection holds embeddables, switch @OneToMany to @ElementCollection + @CollectionTable."],"exampleFix":"// before\n@TargetEmbeddable(Address.class)\n@ManyToOne\nprivate Address address; // Address is an @Embeddable, not an entity\n\n// after\n@TargetEmbeddable(Address.class)\n@Embedded\nprivate Address address;","handlingStrategy":"validation","validationCode":"// verify @TargetEmbeddable is paired with @Embedded or @ElementCollection\nfor (Field f : Order.class.getDeclaredFields()) {\n    if (f.isAnnotationPresent(TargetEmbeddable.class)\n            && !f.isAnnotationPresent(Embedded.class)\n            && !f.isAnnotationPresent(ElementCollection.class)) {\n        throw new IllegalStateException(\"@TargetEmbeddable on non-embedded member: \" + f);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    metadata = sources.buildMetadata();\n} catch (MappingException e) {\n    failBuild(\"Bad @TargetEmbeddable usage: \" + e.getMessage());\n}","preventionTips":["Use @TargetEmbeddable only with @Embedded/@ElementCollection; use @Target for entity associations.","Keep a style rule that embeddable targets are declared right next to the embed annotations."],"tags":["hibernate","orm","target-embeddable","embedded","element-collection","mapping"],"backgroundTag":"annotation-target-misuse","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}