{"record":{"id":"e7cf91c3f5c23de0","repo":"hibernate/hibernate-orm","slug":"association-must-specify-the-referenced-entity","errorCode":null,"errorMessage":"association must specify the referenced entity","messagePattern":"association must specify the referenced entity","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/ToOne.java","lineNumber":118,"sourceCode":"\tpublic boolean isTypeSpecified() {\n\t\treturn referencedEntityName!=null;\n\t}\n\n\t@Override\n\tpublic boolean isSame(SimpleValue other) {\n\t\treturn other instanceof ToOne toOne && isSame( toOne );\n\t}\n\n\tpublic boolean isSame(ToOne other) {\n\t\treturn super.isSame( other )\n\t\t\t&& Objects.equals( referencedPropertyName, other.referencedPropertyName )\n\t\t\t&& Objects.equals( referencedEntityName, other.referencedEntityName );\n\t}\n\n\t@Override\n\tpublic boolean isValid(MappingContext mappingContext) throws MappingException {\n\t\tif ( referencedEntityName==null ) {\n\t\t\tthrow new MappingException(\"association must specify the referenced entity\");\n\t\t}\n\t\treturn super.isValid( mappingContext );\n\t}\n\n\t@Override\n\tpublic boolean isLazy() {\n\t\treturn lazy;\n\t}\n\n\t@Override\n\tpublic void setLazy(boolean lazy) {\n\t\tthis.lazy = lazy;\n\t}\n\n\tpublic boolean isUnwrapProxy() {\n\t\treturn unwrapProxy;\n\t}\n","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/ToOne.java#L100-L136","documentation":"ToOne.isValid() validates every many-to-one/one-to-one style association before the SessionFactory completes. A ToOne must carry a referencedEntityName — the entity being pointed at. If it is null (no target class was resolvable at mapping time), validation aborts with this MappingException because Hibernate cannot build a joinable association to an unnamed target.","triggerScenarios":"hbm.xml <many-to-one name=\"x\"/> with neither class nor target-entity attribute; annotation @ManyToOne on a raw, unparameterized field (Object, untyped generic) with no targetEntity; programmatic mapping forgetting to call setReferencedEntityName; a @OneToOne mapped by generic/wildcard types where reflection cannot infer the target.","commonSituations":"Hand-edited hbm.xml dropping the class attribute; entities using raw types (Map instead of Map<Order,...>) so reflection fails; programmatic boot-model builders assembled in code; copying association mappings and forgetting to adjust the target; Kotlin/Scala generic fields that erase before Hibernate reads them.","solutions":["Specify the target explicitly: <many-to-one name=\"order\" class=\"Order\"/> or @ManyToOne(targetEntity = Order.class).","Use a concrete, parameterized field type (private Order order; not private Object order;) so reflection infers the entity.","In programmatic models, always call manyToOne.setReferencedEntityName(\"Order\") before validation.","Run metadata validation in a unit test to catch this at CI time."],"exampleFix":"// before\n@ManyToOne\nprivate Object customer;\n\n// after\n@ManyToOne(targetEntity = Customer.class)\nprivate Customer customer;","handlingStrategy":"type-guard","validationCode":"// hbm.xml: statically check every <many-to-one>/<one-to-one> has class= before boot\n// annotations: ensure fields are concrete entity types or carry targetEntity","typeGuard":"static boolean resolvesToEntity(Class<?> type) {\n    return type != Object.class && !type.isPrimitive()\n            && !Collection.class.isAssignableFrom(type)\n            && type != Void.class; // crude guard — real check is the mapped-entity lookup\n}","tryCatchPattern":"try {\n    sf = cfg.buildSessionFactory();\n} catch (MappingException e) {\n    if (\"association must specify the referenced entity\".equals(e.getMessage())) {\n        // find the association missing class=/targetEntity — message lacks the name, so check XMLEntityResolver errors or mapping debug logs\n    }\n    throw e;\n}","preventionTips":["Always annotate associations with concrete types or @ManyToOne(targetEntity = X.class).","Avoid raw/unparameterized fields for associations.","Run MetadataBuilder in a unit test — it fails fast listing the mapping file with the defect."],"tags":["hibernate","association","many-to-one","one-to-one","orm-mapping"],"backgroundTag":"unresolved-entity-reference","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}