{"record":{"id":"3a50603c2cf7cdde","repo":"hibernate/hibernate-orm","slug":"the-joincolumn-for-a-secondary-table-must-refer","errorCode":null,"errorMessage":"The '@JoinColumn' for a secondary table must reference the primary key","messagePattern":"The '@JoinColumn' for a secondary table must reference the primary key","errorType":"exception","errorClass":"AnnotationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/TableBinder.java","lineNumber":757,"sourceCode":"\n\tprivate static void bindNonPrimaryKeyReference(\n\t\t\tPersistentClass referencedEntity,\n\t\t\tAnnotatedJoinColumns joinColumns,\n\t\t\tSimpleValue value) {\n\t\tfinal String referencedPropertyName;\n\t\tif ( value instanceof ToOne toOne ) {\n\t\t\treferencedPropertyName = toOne.getReferencedPropertyName();\n\t\t}\n\t\telse if ( value instanceof DependantValue ) {\n\t\t\tfinal String propertyName = joinColumns.getPropertyName();\n\t\t\tif ( propertyName != null ) {\n\t\t\t\tfinal var collection = (Collection)\n\t\t\t\t\t\treferencedEntity.getRecursiveProperty( propertyName )\n\t\t\t\t\t\t\t\t.getValue();\n\t\t\t\treferencedPropertyName = collection.getReferencedPropertyName();\n\t\t\t}\n\t\t\telse {\n\t\t\t\tthrow new AnnotationException( \"The '@JoinColumn' for a secondary table must reference the primary key\" );\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\tthrow new AssertionFailure( \"Property ref to an unexpected Value type: \" + value.getClass().getName() );\n\t\t}\n\t\tif ( referencedPropertyName == null ) {\n\t\t\tthrow new AssertionFailure( \"No property ref found\" );\n\t\t}\n\n\t\tfinal var synthProp = referencedEntity.getReferencedProperty( referencedPropertyName );\n\t\tif ( synthProp == null ) {\n\t\t\tthrow new AssertionFailure( \"Cannot find synthetic property: \"\n\t\t\t\t\t+ referencedEntity.getEntityName() + \".\" + referencedPropertyName );\n\t\t}\n\t\tlinkJoinColumnWithValueOverridingNameIfImplicit( referencedEntity, synthProp.getValue(), joinColumns, value );\n\t\tcheckReferenceToUniqueKey( value, synthProp );\n\t\t( (SortableValue) value ).sortProperties();\n\t}","sourceCodeStart":739,"sourceCodeEnd":775,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/TableBinder.java#L739-L775","documentation":"Error \"The '@JoinColumn' for a secondary table must reference the primary key\" thrown in hibernate/hibernate-orm.","triggerScenarios":"A '@JoinColumn' / 'referencedColumnName' does not line up with the columns mapped by the target entity.","commonSituations":"Composite foreign keys, associations to entities with secondary tables, or reordered/duplicated referencedColumnName values across multiple @JoinColumn declarations.","solutions":["Make the secondary table @JoinColumn reference the primary key column of the main table."],"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"}