hibernate/hibernate-orm · error · MappingException

Unique key constraint involves formulas

Error message

Unique key constraint involves formulas

What it means

createUniqueKey() was invoked on a value that contains formulas. SQL unique constraints can only cover real columns, so SimpleValue refuses to build a unique key when hasFormula() is true. The mapping asks the database to enforce uniqueness over a computed expression, which a constraint cannot do.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java:412

	protected boolean hasAuxiliaryColumnInPrimaryKey(PersistentClass referencedEntity) {
		return referencedEntity.getRootClass().isAuxiliaryColumnInPrimaryKey();
	}

	protected boolean hasAuxiliaryColumnInPrimaryKey(String entityName) {
		if ( entityName == null ) {
			return false;
		}
		else {
			final var referencedEntity = metadata.getEntityBinding( entityName );
			return referencedEntity != null && hasAuxiliaryColumnInPrimaryKey( referencedEntity );
		}
	}

	@Override
	public void createUniqueKey(MetadataBuildingContext context) {
		if ( hasFormula() ) {
			throw new MappingException( "Unique key constraint involves formulas" );
		}
		getTable().createUniqueKey( getConstraintColumns(), context );
	}

	@Internal
	public void setCustomIdGeneratorCreator(GeneratorCreator customIdGeneratorCreator) {
		this.customIdGeneratorCreator = customIdGeneratorCreator;
	}

	@Internal
	public GeneratorCreator getCustomIdGeneratorCreator() {
		return customIdGeneratorCreator;
	}

	@Override
	@Remove
	public Generator createGenerator(
			Dialect dialect,

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove the unique flag from the formula-based property
2. Put the unique constraint on the real underlying column instead
3. If uniqueness of a computed value is required, use a real (possibly generated) column with a DB-level constraint, or enforce it in application code

Example fix

// before
<property name="normalizedCode" unique="true">
  <formula>upper(code)</formula>
</property>

// after
<property name="code" unique="true"/>
<!-- drop uniqueness on the formula -->

for (PersistentClass pc : metadata.getEntityBindings()) {
    for (Property p : pc.getProperties()) {
        if (p.getValue() instanceof SimpleValue sv && sv.hasFormula() && sv.isUnique()) {
            // uniqueness requested on a formula; remove the unique flag or map a real column
        }
    }
}

static boolean isUniqueOverFormula(SimpleValue sv) {
    return sv.hasFormula() && sv.isUnique();
}

When it happens

Trigger: An hbm property marked unique=true whose value contains a formula element; uniqueness requested on a mapping that mixes in formulas; programmatic unique-key creation on a value holding Formula entries.

Common situations: Formula-based derived properties accidentally marked unique; mapping tools that set unique broadly; attempts to enforce uniqueness of computed values like upper(name).

Related errors

• Identifier property '" + getPath( holder, data ) + "' cannot
• Expecting column for collection id (idbag), but found formul
• Expecting single column in context of <%s name="%s"/>, but f
• formula attribute may not be specified along with <column/>
• Unable to determine SQL type name for column '%s' of table '

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