{"record":{"id":"626b3f7ace991f3f","repo":"hibernate/hibernate-orm","slug":"referenced-column-mapped-by-target-property","errorCode":null,"errorMessage":"Referenced column '{}' mapped by target property '{}' occurs out of order in the list of '@JoinColumn's for association {}","messagePattern":"Referenced column '(.+?)' mapped by target property '(.+?)' occurs out of order in the list of '@JoinColumn's for association (.+?)","errorType":"exception","errorClass":"AnnotationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/BinderHelper.java","lineNumber":506,"sourceCode":"\t\t//       that could be made to work for a different choice of\n\t\t//       properties (it's also not very deterministic)\n\t\tfinal List<Property> orderedProperties = new ArrayList<>();\n\t\tint lastPropertyColumnIndex = 0;\n\t\tProperty currentProperty = null;\n\t\tfor ( Column column : orderedColumns ) {\n\t\t\tfinal Set<Property> properties = columnsToProperty.get( column );\n\t\t\tif ( properties.isEmpty() ) {\n\t\t\t\t// no property found which maps to this column\n\t\t\t\tthrow new AnnotationException( \"Referenced column '\" + column.getName()\n\t\t\t\t\t\t+ \"' in '@JoinColumn' for \" + associationMessage( associatedEntity, columns )\n\t\t\t\t\t\t+ \" is not mapped by any property of the target entity\" );\n\t\t\t}\n\t\t\tfor ( Property property : properties ) {\n\t\t\t\tif ( property == currentProperty ) {\n\t\t\t\t\t// we have the next column of the previous property\n\t\t\t\t\tif ( !property.getColumns().get( lastPropertyColumnIndex ).equals( column ) ) {\n\t\t\t\t\t\t// the columns have to occur in the right order in the property\n\t\t\t\t\t\tthrow new AnnotationException( \"Referenced column '\" + column.getName()\n\t\t\t\t\t\t\t\t+ \"' mapped by target property '\" + property.getName()\n\t\t\t\t\t\t\t\t+ \"' occurs out of order in the list of '@JoinColumn's for association \"\n\t\t\t\t\t\t\t\t+ associationMessage( associatedEntity, columns ) );\n\t\t\t\t\t}\n\t\t\t\t\tlastPropertyColumnIndex++;\n\t\t\t\t\tif ( lastPropertyColumnIndex == currentProperty.getColumnSpan() ) {\n\t\t\t\t\t\t//we have exhausted the columns in this property\n\t\t\t\t\t\tcurrentProperty = null;\n\t\t\t\t\t\tlastPropertyColumnIndex = 0;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\telse if ( currentProperty != null ) {\n\t\t\t\t\t// we didn't use up all the columns of the previous property\n\t\t\t\t\tthrow new AnnotationException( \"Target property '\" + property.getName() + \"' has \"\n\t\t\t\t\t\t\t+ property.getColumnSpan() + \" columns which must be referenced by a '@JoinColumn' for \"\n\t\t\t\t\t\t\t+ associationMessage( associatedEntity, columns )\n\t\t\t\t\t\t\t+ \" (every column mapped by '\" + property.getName()\n\t\t\t\t\t\t\t+ \"' must occur exactly once as a 'referencedColumnName', and in the correct order)\" );","sourceCodeStart":488,"sourceCodeEnd":524,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/BinderHelper.java#L488-L524","documentation":"Error \"Referenced column '{}' mapped by target property '{}' occurs out of order in the list of '@JoinColumn's for association {}\" 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":["Reorder the @JoinColumn list so the referenced columns occur in the same order as the columns of the referenced target property."],"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"}