{"record":{"id":"25e5d251923b666c","repo":"hibernate/hibernate-orm","slug":"embeddedtable-only-supported-for-use-on-entity-or","errorCode":null,"errorMessage":"@EmbeddedTable only supported for use on entity or mapped-superclass","messagePattern":"@EmbeddedTable only supported for use on entity or mapped-superclass","errorType":"exception","errorClass":"AnnotationPlacementException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java","lineNumber":1106,"sourceCode":"\tprivate Collection getCollection() {\n\t\treturn collection;\n\t}\n\n\tprivate void setPropertyName(String propertyName) {\n\t\tthis.propertyName = propertyName;\n\t}\n\n\tprivate void setDeclaringClass(ClassDetails declaringClass) {\n\t\tthis.declaringClass = declaringClass;\n\t\tthis.declaringClassSet = true;\n\t}\n\n\tprivate void bind() {\n\t\tif ( property != null ) {\n\t\t\tfinal EmbeddedTable misplaced = property.getDirectAnnotationUsage( EmbeddedTable.class );\n\t\t\tif ( misplaced != null ) {\n\t\t\t\t// not allowed\n\t\t\t\tthrow new AnnotationPlacementException( \"@EmbeddedTable only supported for use on entity or mapped-superclass\" );\n\t\t\t}\n\t\t}\n\t\tcollection = createCollection( propertyHolder.getPersistentClass() );\n\t\tfinal String role = qualify( propertyHolder.getPath(), propertyName );\n\t\tBOOT_LOGGER.bindingCollectionRole( role );\n\t\tcollection.setRole( role );\n\t\tcollection.setMappedByProperty( mappedBy );\n\n\t\tcheckMapKeyColumn();\n\t\t//set laziness\n\t\tdefineFetchingStrategy();\n\t\tcollection.setMutable( isMutable() );\n\t\t//work on association\n\t\tfinal boolean isUnowned = isUnownedCollection();\n\t\tbindOptimisticLock( isUnowned );\n\t\tapplySortingAndOrdering();\n\t\tbindCache();\n\t\tbindLoader();","sourceCodeStart":1088,"sourceCodeEnd":1124,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java#L1088-L1124","documentation":"@EmbeddedTable is a class-level annotation that only applies to entity classes and mapped superclasses. CollectionBinder.bind() throws this AnnotationPlacementException when it finds @EmbeddedTable placed directly on a collection property, because an embedded table cannot govern a collection attribute.","triggerScenarios":"bind() runs for a collection property whose direct annotations include EmbeddedTable (property.getDirectAnnotationUsage(EmbeddedTable.class) != null).","commonSituations":"Adopting the @EmbeddedTable feature and annotating every mapped member 'just in case'; annotation auto-completion inserting @EmbeddedTable at field level; migrating from @SecondaryTable-style splits and placing the table hint on properties.","solutions":["Remove @EmbeddedTable from the collection property","Place @EmbeddedTable on the entity class or mapped superclass where it is supported","For collections that need their own table, use @CollectionTable / @JoinTable instead"],"exampleFix":"// before\n@Entity\npublic class Order {\n    @EmbeddedTable(name = \"order_extra\")   // error: not allowed on a collection attribute\n    @ElementCollection\n    Set<String> tags;\n}\n\n// after\n@Entity\n@EmbeddedTable(name = \"order_extra\")      // class-level placement only\npublic class Order {\n    @ElementCollection\n    @CollectionTable(name = \"order_tags\",\n        joinColumns = @JoinColumn(name = \"order_id\"))\n    Set<String> tags;\n}","handlingStrategy":"validation","validationCode":"// Reject @EmbeddedTable placed on properties instead of classes\nstatic void checkEmbeddedTablePlacement(Class<?>... entities) {\n    for ( Class<?> c : entities ) {\n        for ( Field f : c.getDeclaredFields() ) {\n            if ( f.isAnnotationPresent( EmbeddedTable.class ) ) {\n                throw new IllegalStateException( \"@EmbeddedTable on property \"\n                    + c.getName() + \".\" + f.getName() + \" (only class level is supported)\" );\n            }\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat @EmbeddedTable as class-level only: entity or mapped-superclass","Use @CollectionTable/@JoinTable for collection tables, not @EmbeddedTable","Disable annotation auto-completion suggestions for placement-restricted annotations in review checklists"],"tags":["hibernate","embedded-table","annotation-placement","collection-mapping"],"backgroundTag":"annotation-placement-error","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}