{"record":{"id":"d95b577cf4e05df2","repo":"hibernate/hibernate-orm","slug":"unable-to-determine-foreign-key-target-type-for-ma","errorCode":null,"errorMessage":"Unable to determine foreign key target Type for many-to-one or one-to-one mapping: referenced-entity-name=[${associatedEntityName}], referenced-entity-attribute-name=[${lhsPropertyName}]","messagePattern":"Unable to determine foreign key target Type for many-to-one or one-to-one mapping: referenced-entity-name=\\[(.+?)\\], referenced-entity-attribute-name=\\[(.+?)\\]","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/EntityType.java","lineNumber":742,"sourceCode":"\t\t\tresult = factory.getMappingMetamodel().getEntityDescriptor( entityName )\n\t\t\t\t\t.loadByUniqueKey( uniqueKeyPropertyName, key, session );\n\t\t\tif ( result != null ) {\n\t\t\t\t// If the entity was not in the persistence context,\n\t\t\t\t// but was found now, add it to the persistence context\n\t\t\t\tpersistenceContext.addEntity( entityUniqueKey, result );\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\tresult = entity;\n\t\t}\n\n\t\treturn result == null ? null : persistenceContext.proxyFor( result );\n\t}\n\n\tprotected Type requireIdentifierOrUniqueKeyType(MappingContext mapping) {\n\t\tfinal Type targetType = getIdentifierOrUniqueKeyType( mapping );\n\t\tif ( targetType == null ) {\n\t\t\tthrow new MappingException(\n\t\t\t\t\t\"Unable to determine foreign key target Type for many-to-one or one-to-one mapping: \" +\n\t\t\t\t\t\t\t\"referenced-entity-name=[\" + getAssociatedEntityName() +\n\t\t\t\t\t\t\t\"], referenced-entity-attribute-name=[\" + getLHSPropertyName() + \"]\"\n\t\t\t);\n\t\t}\n\t\treturn targetType;\n\t}\n}\n","sourceCodeStart":724,"sourceCodeEnd":751,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/EntityType.java#L724-L751","documentation":"EntityType.requireIdentifierOrUniqueKeyType (EntityType.java:734-744) resolves the type of the foreign key target for a many-to-one/one-to-one: the referenced entity's identifier, or the property referenced by property-ref/referencedPropertyName. When getIdentifierOrUniqueKeyType returns null - the referenced entity or referenced property could not be resolved from the mapping metadata - it throws MappingException naming the referenced entity and the referenced attribute, so you can trace exactly which association is broken.","triggerScenarios":"@ManyToOne/@OneToOne pointing at a class that is not a registered entity (missing @Entity, not in the persistence unit / not scanned); a wrong entityName in @ManyToOne(targetEntity=...) or <many-to-one class=...>; @OneToOne(mappedBy/referencedPropertyName) naming a property that does not exist on the target; hbm.xml <many-to-one> with a property-ref to a non-unique or missing property; circular mappings where the target's id type is itself unresolved.","commonSituations":"Entities excluded by explicit class lists in persistence.xml; annotation scanning gaps after moving classes between modules; refactoring property names referenced by mappedBy/property-ref; copy-pasted mappings referencing old class names; @IdClass/@EmbeddedId on the target that fails to resolve earlier.","solutions":["Verify the referenced entity is mapped: annotated @Entity and included in the persistence unit / scanned package.","Fix the target name spelled in the message: correct targetEntity/class FQN or entityName; remove stale property-ref/referencedPropertyName values.","Ensure the referenced property on the target exists and is the identifier or a unique column, and that the target's own @Id/@EmbeddedId/@IdClass mapping resolves cleanly.","Enable startup logging for mapping metadata to see the preceding warnings about unresolvable classes/properties."],"exampleFix":"// before\n@Entity public class Order {\n    @ManyToOne(targetEntity = Custmr.class) // wrong/unknown target\n    private Custmr customer;\n}\n\n// after\n@Entity public class Order {\n    @ManyToOne(fetch = FetchType.LAZY)\n    private Customer customer; // Customer is @Entity and in the persistence unit\n}","handlingStrategy":"validation","validationCode":"// Startup smoke test: every association must resolve its target in this persistence unit\nfor (EntityType<?> et : emf.getMetamodel().getEntities()) {\n    for (SingularAttribute<?, ?> a : et.getSingularAttributes()) {\n        if (a.getPersistentAttributeType() == PersistentAttributeType.MANY_TO_ONE\n                || a.getPersistentAttributeType() == PersistentAttributeType.ONE_TO_ONE) {\n            Type<?> target = ((SingularAttribute<?, ?>) a).getType();\n            if (target.getPersistenceType() != Type.PersistenceType.ENTITY) {\n                throw new IllegalStateException(\n                    et.getName() + \".\" + a.getName() + \" references unresolvable target\");\n            }\n        }\n    }\n}","typeGuard":"static boolean isMappedEntity(Metamodel mm, Class<?> target) {\n    try { mm.entity(target); return true; }\n    catch (IllegalArgumentException e) { return false; }\n}","tryCatchPattern":"try {\n    return em.createEntityManager(...); // first use / bootstrap\n} catch (PersistenceException e) {\n    if (e.getCause() instanceof MappingException me\n            && me.getMessage().contains(\"Unable to determine foreign key target Type\")) {\n        throw new ConfigurationException(\n            \"Broken @ManyToOne/@OneToOne referenced in: \" + me.getMessage(), me);\n    }\n    throw e;\n}","preventionTips":["Keep explicit lists of entity classes in sync with refactors, or rely on package scanning.","After renaming properties referenced by mappedBy/referencedPropertyName, search mappings for the old name.","Build the SessionFactory in a fast unit test so mapping errors surface at build time, not at first deployment."],"tags":["hibernate","mapping","many-to-one","one-to-one","foreign-key","bootstrap"],"backgroundTag":"unresolved-entity-mapping","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}