hibernate/hibernate-orm · error · MappingException

collection foreign key mappingContext has wrong number of co

Error message

collection foreign key mappingContext has wrong number of columns: {} type: {}

What it means

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.

Source

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

		this.batchSize = batchSize;
	}

	@Override
	public FetchStyle getFetchStyle() {
		return fetchStyle;
	}

	@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();
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Align the collection key columns with the owner identifier: for composite ids declare one join column per id column.
2. In annotations use @JoinColumns listing all columns; in hbm list every <key column="..."/>.
3. For custom key types spanning multiple columns, provide all of their columns on the key.

Example fix

// before: owner uses @EmbeddedId with two id columns, only one join column declared
@OneToMany
@JoinColumn(name = "invoice_number")
private List<Line> lines;

// after
@OneToMany
@JoinColumns({
    @JoinColumn(name = "invoice_company"),
    @JoinColumn(name = "invoice_number")
})
private List<Line> lines;

try {
    SessionFactory sf = configuration.buildSessionFactory();
}
catch ( MappingException e ) {
    // message: collection foreign key ... wrong number of columns: <role>
    // compare the collection key columns against the owner identifier columns
}

When it happens

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

Common situations: Changing an entity from simple to composite id without updating collection mappings; hand-written hbm join column lists; copy-pasted @JoinColumn annotations.

Related errors

• Foreign key ({}:{} [{}])) must have same number of columns a
• null key for collection: {}
• Number of referencing columns [%s] did not match number of r
• Unable to determine foreign key target Type for many-to-one
• The INSERT statement for table [%s] contains no column, and

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