hibernate/hibernate-orm · error · MappingException

collection index mapping has wrong number of columns: " + ge

Error message

collection index mapping has wrong number of columns: " + getRole() + " type: " + getIndex().getType().getName()

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/IndexedCollection.java:104

		}
//		else {
			// don't create a unique key, 'cos some
			// databases don't like a UK on nullable
			// columns
			/*ArrayList list = new ArrayList();
			list.addAll( getKey().getConstraintColumns() );
			list.addAll( getIndex().getConstraintColumns() );
			getCollectionTable().createUniqueKey(list);*/
//		}
	}

	public void validate(MappingContext mappingContext) throws MappingException {
		super.validate( mappingContext );

		assert getElement() != null : "IndexedCollection index not bound : " + getRole();

		if ( !getIndex().isValid( mappingContext ) ) {
			throw new MappingException(
					"collection index mapping has wrong number of columns: " +
							getRole() +
							" type: " +
							getIndex().getType().getName()
			);
		}
	}


	public boolean isList() {
		return false;
	}
}

View on GitHub (pinned to fad1729dce)

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.

Example fix

// before - entity used as map key without key-column mapping
@ElementCollection
Map<Item, String> names;

// after
@ElementCollection
@MapKeyJoinColumn(name = "item_id")
Map<Item, String> names;

Defensive patterns

Strategy: try-catch

Try / catch

try {
    metadata = sources.buildMetadata();
} catch (MappingException e) {
    // message names the collection role + index type - inspect that
    // collection's key annotations (@MapKey*, @OrderColumn)
    throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/77f35036f4bb56a3. Report an issue: GitHub.