hibernate/hibernate-orm · error · MappingException

subclass key mapping has wrong number of columns: " + getEnt

Error message

subclass key mapping has wrong number of columns: " + getEntityName() + " type: " + key.getType().getName()

What it means

JoinedSubclass#validate checks the shared key of a JOINED inheritance subclass and throws when the key Value's column span does not match its type. With JOINED inheritance the subclass table's primary/foreign key must align exactly with the parent's key mapping.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/JoinedSubclass.java:47

	}

	public void setTable(Table table) {
		this.table = table;
		getSuperclass().addSubclassTable( table );
	}

	public KeyValue getKey() {
		return key;
	}

	public void setKey(KeyValue key) {
		this.key = key;
	}

	public void validate(Metadata mapping) throws MappingException {
		super.validate( mapping );
		if ( key != null && !key.isValid( mapping ) ) {
			throw new MappingException(
					"subclass key mapping has wrong number of columns: " +
					getEntityName() +
					" type: " +
					key.getType().getName()
				);
		}
	}

	public Object accept(PersistentClassVisitor mv) {
		return mv.accept(this);
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Add @PrimaryKeyJoinColumns to the subclass with one @PrimaryKeyJoinColumn per parent PK column (explicit referencedColumnName).
If the parent key changed, update all JOINED subclasses' key mappings in the same commit.
In hbm, list all key columns inside the subclass <key> element.

Example fix

// before - composite parent PK, subclass key incomplete
@Entity
@Inheritance(strategy = InheritanceType.JOINED)
public class Parent { @EmbeddedId CompId id; }

@Entity
public class Child extends Parent { }

// after
@Entity
@PrimaryKeyJoinColumns({
    @PrimaryKeyJoinColumn(name = "a", referencedColumnName = "a"),
    @PrimaryKeyJoinColumn(name = "b", referencedColumnName = "b")
})
public class Child extends Parent { }

Defensive patterns

Strategy: try-catch

Try / catch

try {
    metadata = sources.buildMetadata();
} catch (MappingException e) {
    // message names the subclass entity + key type - compare its join
    // column list with the parent's PK columns
    throw e;
}

Prevention

For composite ids always declare @PrimaryKeyJoinColumns explicitly on every JOINED subclass.
When the parent key shape changes, update all JOINED subclasses in the same commit.
Validate full inheritance hierarchies with a metadata build test.

When it happens

Trigger: Parent uses a composite @EmbeddedId/@IdClass but the subclass lacks @PrimaryKeyJoinColumns covering all key columns; a PK column was added to the parent hierarchy without updating subclass join columns; an hbm subclass <key> lists fewer <column> entries than the parent key.

Common situations: Composite keys introduced into an existing JOINED hierarchy; refactoring from single-column to composite ids; hand-written hbm subclass joins.

Related errors

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