{"record":{"id":"ff98cb2245db6290","repo":"hibernate/hibernate-orm","slug":"collection-foreign-key-mappingcontext-has-wrong-nu","errorCode":null,"errorMessage":"collection foreign key mappingContext has wrong number of columns: {} type: {}","messagePattern":"collection foreign key mappingContext has wrong number of columns: (.+?) type: (.+?)","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/Collection.java","lineNumber":399,"sourceCode":"\t\tthis.batchSize = batchSize;\n\t}\n\n\t@Override\n\tpublic FetchStyle getFetchStyle() {\n\t\treturn fetchStyle;\n\t}\n\n\t@Override\n\tpublic void setFetchStyle(FetchStyle fetchStyle) {\n\t\tthis.fetchStyle = fetchStyle;\n\t}\n\n\tpublic void validate(MappingContext mappingContext) throws MappingException {\n\t\tassert getKey() != null : \"Collection key not bound : \" + getRole();\n\t\tassert getElement() != null : \"Collection element not bound : \" + getRole();\n\n\t\tif ( !getKey().isValid( mappingContext ) ) {\n\t\t\tthrow new MappingException(\n\t\t\t\t\t\"collection foreign key mappingContext has wrong number of columns: \"\n\t\t\t\t\t\t\t+ getRole()\n\t\t\t\t\t\t\t+ \" type: \"\n\t\t\t\t\t\t\t+ getKey().getType().getName()\n\t\t\t);\n\t\t}\n\t\tif ( !getElement().isValid( mappingContext ) ) {\n\t\t\tthrow new MappingException(\n\t\t\t\t\t\"collection element mappingContext has wrong number of columns: \"\n\t\t\t\t\t\t\t+ getRole()\n\t\t\t\t\t\t\t+ \" type: \"\n\t\t\t\t\t\t\t+ getElement().getType().getName()\n\t\t\t);\n\t\t}\n\n\t\tcheckColumnDuplication();\n\t}\n","sourceCodeStart":381,"sourceCodeEnd":417,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/Collection.java#L381-L417","documentation":"Collection.validate checks the collection's foreign key (the key Value referencing the owner): the key type's column span must match the number of mapped key columns (key.isValid). A mismatch aborts bootstrap with the collection role and key type name.","triggerScenarios":"Owner entity has a composite identifier (@EmbeddedId/@IdClass) but the collection key declares a single column, or vice versa; @OneToMany/@JoinColumn list not matching the owner id column count; hbm <key> listing the wrong columns; custom key type spanning multiple columns mapped with one.","commonSituations":"Changing an entity from simple to composite id without updating collection mappings; hand-written hbm join column lists; copy-pasted @JoinColumn annotations.","solutions":["Align the collection key columns with the owner identifier: for composite ids declare one join column per id column.","In annotations use @JoinColumns listing all columns; in hbm list every <key column=\"...\"/>.","For custom key types spanning multiple columns, provide all of their columns on the key."],"exampleFix":"// before: owner uses @EmbeddedId with two id columns, only one join column declared\n@OneToMany\n@JoinColumn(name = \"invoice_number\")\nprivate List<Line> lines;\n\n// after\n@OneToMany\n@JoinColumns({\n    @JoinColumn(name = \"invoice_company\"),\n    @JoinColumn(name = \"invoice_number\")\n})\nprivate List<Line> lines;","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    SessionFactory sf = configuration.buildSessionFactory();\n}\ncatch ( MappingException e ) {\n    // message: collection foreign key ... wrong number of columns: <role>\n    // compare the collection key columns against the owner identifier columns\n}","preventionTips":["When changing an entity id to composite, update every collection key mapping in the same change","Prefer derived (mappedBy) associations so Hibernate computes key columns","Add a mapping smoke test that builds the full SessionFactory in CI"],"tags":["hibernate","collection","foreign-key","mapping"],"backgroundTag":"column-count-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}