{"record":{"id":"77f35036f4bb56a3","repo":"hibernate/hibernate-orm","slug":"collection-index-mapping-has-wrong-number-of-colum","errorCode":null,"errorMessage":"collection index mapping has wrong number of columns: \" + getRole() + \" type: \" + getIndex().getType().getName()","messagePattern":"collection index mapping has wrong number of columns: \" \\+ getRole\\(\\) \\+ \" type: \" \\+ getIndex\\(\\)\\.getType\\(\\)\\.getName\\(\\)","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/IndexedCollection.java","lineNumber":104,"sourceCode":"\t\t}\n//\t\telse {\n\t\t\t// don't create a unique key, 'cos some\n\t\t\t// databases don't like a UK on nullable\n\t\t\t// columns\n\t\t\t/*ArrayList list = new ArrayList();\n\t\t\tlist.addAll( getKey().getConstraintColumns() );\n\t\t\tlist.addAll( getIndex().getConstraintColumns() );\n\t\t\tgetCollectionTable().createUniqueKey(list);*/\n//\t\t}\n\t}\n\n\tpublic void validate(MappingContext mappingContext) throws MappingException {\n\t\tsuper.validate( mappingContext );\n\n\t\tassert getElement() != null : \"IndexedCollection index not bound : \" + getRole();\n\n\t\tif ( !getIndex().isValid( mappingContext ) ) {\n\t\t\tthrow new MappingException(\n\t\t\t\t\t\"collection index mapping has wrong number of columns: \" +\n\t\t\t\t\t\t\tgetRole() +\n\t\t\t\t\t\t\t\" type: \" +\n\t\t\t\t\t\t\tgetIndex().getType().getName()\n\t\t\t);\n\t\t}\n\t}\n\n\n\tpublic boolean isList() {\n\t\treturn false;\n\t}\n}\n","sourceCodeStart":86,"sourceCodeEnd":118,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/IndexedCollection.java#L86-L118","documentation":"IndexedCollection#validate verifies the index (map key or list position) of an indexed collection and throws when the index Value is invalid - in practice its column span does not match the index type, so the key cannot be stored.","triggerScenarios":"An @ElementCollection Map whose entity key is missing @MapKeyJoinColumn; a composite/embeddable map key missing @MapKeyClass or with incomplete key column mapping; @OrderColumn/@ListIndex combined with a type spanning several columns; hbm <map-key> type/column mismatches.","commonSituations":"Adding Map fields with entity or embeddable keys without the key annotations; switching Map key types; custom types used as map keys; migrating hbm <map> elements.","solutions":["For entity keys add @MapKeyJoinColumn; for embeddable keys add @MapKeyClass and map the key columns (@MapKeyColumn / attribute overrides).","Ensure basic map keys have @MapKeyColumn when the default naming/column setup does not fit.","Check that the index type is single-column or fully mapped, using the role and type name from the message to locate the collection."],"exampleFix":"// before - entity used as map key without key-column mapping\n@ElementCollection\nMap<Item, String> names;\n\n// after\n@ElementCollection\n@MapKeyJoinColumn(name = \"item_id\")\nMap<Item, String> names;","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    metadata = sources.buildMetadata();\n} catch (MappingException e) {\n    // message names the collection role + index type - inspect that\n    // collection's key annotations (@MapKey*, @OrderColumn)\n    throw e;\n}","preventionTips":["Always annotate Map keys explicitly: @MapKeyClass, @MapKeyJoinColumn, or @MapKeyColumn.","Avoid composite map keys when a basic String/number key suffices.","Build Metadata for all mappings in CI tests so key mismatches fail early."],"tags":["hibernate","orm","mapping","map-key","collection-index","element-collection"],"backgroundTag":"collection-index-mapping-error","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}