hibernate/hibernate-orm · error · MappingException

collection element mappingContext has wrong number of column

Error message

collection element mappingContext has wrong number of columns: {} type: {}

What it means

Companion check to the key validation: the collection element value (element-collection column, target entity FK, or composite element) must have a type whose column span matches the mapped columns (element.isValid). A mismatch throws MappingException with the collection role and element type name.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/Collection.java:407

	@Override
	public void setFetchStyle(FetchStyle fetchStyle) {
		this.fetchStyle = fetchStyle;
	}

	public void validate(MappingContext mappingContext) throws MappingException {
		assert getKey() != null : "Collection key not bound : " + getRole();
		assert getElement() != null : "Collection element not bound : " + getRole();

		if ( !getKey().isValid( mappingContext ) ) {
			throw new MappingException(
					"collection foreign key mappingContext has wrong number of columns: "
							+ getRole()
							+ " type: "
							+ getKey().getType().getName()
			);
		}
		if ( !getElement().isValid( mappingContext ) ) {
			throw new MappingException(
					"collection element mappingContext has wrong number of columns: "
							+ getRole()
							+ " type: "
							+ getElement().getType().getName()
			);
		}

		checkColumnDuplication();
	}

	private void checkColumnDuplication() throws MappingException {
		final String owner = "collection '" + getReferencedPropertyName() + "'";
		final HashSet<QualifiedColumnName> cols = new HashSet<>();
		getKey().checkColumnDuplication( cols, owner );
		if ( isIndexed() ) {
			( (IndexedCollection) this ).getIndex().checkColumnDuplication( cols, owner );
		}
		if ( isIdentified() ) {

View on GitHub (pinned to fad1729dce)

Solutions

Make the element's declared columns match the element type's column span, in order.
For multi-column custom types, list all columns with @Columns({@Column(...), @Column(...)}).
Verify many-to-many join column lists against both endpoints' identifiers.

Example fix

// before: TagUserType spans 2 columns but only one column declared
@ElementCollection
@Type(TagUserType.class)
@Column(name = "tag")
private List<Tag> tags;

// after
@ElementCollection
@Type(TagUserType.class)
@Columns({ @Column(name = "tag"), @Column(name = "tag_lang") })
private List<Tag> tags;

Defensive patterns

Strategy: validation

Try / catch

try {
    SessionFactory sf = configuration.buildSessionFactory();
}
catch ( MappingException e ) {
    // message: collection element ... wrong number of columns: <role>
    // compare declared element columns against the element type column span
}

Prevention

List all columns of multi-column custom types with @Columns
Regenerate or review collection column lists after embeddable changes
Verify many-to-many join tables against both endpoint identifiers

When it happens

Trigger: @ElementCollection over a custom type spanning two columns while only one @Column is declared; hbm <composite-element> with a wrong column count; many-to-many join columns not matching the target id span; formulas offsetting element column spans.

Common situations: Adding fields to embeddables without updating collection column lists; hand-maintained hbm components; switching attributes between basic and multi-column custom types.

Related errors

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