hibernate/hibernate-orm · error · MappingException

Property '" + qualify( getEntityName(), prop.getName() ) + "

Error message

Property '" + qualify( getEntityName(), prop.getName() ) + "' maps to " + actualColumns + " columns but " + requiredColumns + " columns are required (type '" + type.getName() + "' spans " + requiredColumns + " columns)

What it means

Mapping validation failed because the number of columns a property maps to does not match the number its Hibernate type requires. PersistentClass.validate() calls Property.isValid(); when invalid, it compares prop.getColumnSpan() (columns actually mapped) with type.getColumnSpan(mapping) (columns the type spans) and reports both numbers. The property's column mapping and its resolved type disagree.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java:702

			|| getSuperMappedSuperclass() != null && getSuperMappedSuperclass().isPropertyDefinedInHierarchy( name )
			|| getSuperclass() != null && getSuperclass().isPropertyDefinedInHierarchy( name );
	}

	public OptimisticLockStyle getOptimisticLockStyle() {
		return optimisticLockStyle;
	}

	public void setOptimisticLockStyle(OptimisticLockStyle optimisticLockStyle) {
		this.optimisticLockStyle = optimisticLockStyle;
	}

	public void validate(Metadata mapping) throws MappingException {
		for ( var prop : getProperties() ) {
			if ( !prop.isValid( mapping ) ) {
				final var type = prop.getType();
				final int actualColumns = prop.getColumnSpan();
				final int requiredColumns = type.getColumnSpan( mapping );
				throw new MappingException(
						"Property '" + qualify( getEntityName(), prop.getName() )
								+ "' maps to " + actualColumns + " columns but " + requiredColumns
								+ " columns are required (type '" + type.getName()
								+ "' spans " + requiredColumns + " columns)"
				);
			}
		}
		checkPropertyDuplication();
		checkColumnDuplication();
	}

	private void checkPropertyDuplication() throws MappingException {
		final HashSet<String> names = new HashSet<>();
		for ( var property : getProperties() ) {
			if ( !names.add( property.getName() ) ) {
				throw new MappingException( "Duplicate property mapping of " + property.getName() + " found in " + getEntityName() );
			}
		}

View on GitHub (pinned to fad1729dce)

Solutions

Read the two numbers in the message and add or remove @Column/@Columns entries so the mapped count equals the required count
For custom types, check the type's declared column span against the mapped columns
For embeddables, verify @AttributeOverride lists cover exactly the component's columns
After a Hibernate upgrade, re-check types whose span semantics changed

Example fix

// before
@Columns(columns = @Column(name = "v1"))
private MonetaryAmount amount; // MonetaryAmount spans 2 columns

// after
@Columns(columns = {@Column(name = "v1"), @Column(name = "v2")})
private MonetaryAmount amount;

Defensive patterns

Strategy: validation

Validate before calling

for (PersistentClass pc : metadata.getEntityBindings()) {
    for (Property p : pc.getProperties()) {
        int mapped = p.getColumnSpan();
        int required = p.getType().getColumnSpan((Mapping) metadata);
        if (mapped != required) {
            // report entity and property before the SessionFactory build fails
        }
    }
}

Try / catch

try { metadata.buildSessionFactory(); }
catch (MappingException e) {
    if (e.getMessage().contains("columns are required")) {
        // read the two counts from the message and align the @Columns list
    }
    throw e;
}

Prevention

Document the column span of custom types next to their registration
Run a mapping-validation test after every Hibernate upgrade
Prefer standard types; wrap multi-column types in a well-tested AggregateJdbcType

When it happens

Trigger: A custom UserType or composite type that spans 2 columns while only one @Column is declared (or the reverse); @Columns with the wrong element count; an @Embedded whose override set lost or added columns; a formula used where the type requires real columns.

Common situations: Upgrading Hibernate so the resolved type for a Java type changes its column span; composite-user-type migration in 6.x; hand-written hbm with stale column lists after type changes.

Related errors

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