What causes "constraint involves a formula: {}" in hibernate/hibernate-orm?

Map constrained parts (id members, PK columns, unique key members) to real database columns instead of formulas.

hibernate/hibernate-orm · error · MappingException

constraint involves a formula: {}

Error message

constraint involves a formula: {}

What it means

Constraint#addColumns throws when a primary key or unique constraint is being built over a Value that contains a formula instead of a physical column. Databases cannot enforce constraints on computed select fragments, so Hibernate refuses the mapping instead of generating invalid DDL.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/Constraint.java:56

	public String getOptions() {
		return options;
	}

	public void setOptions(String options) {
		this.options = options;
	}

	public void addColumn(Column column) {
		if ( !columns.contains( column ) ) {
			columns.add( column );
		}
	}

	public void addColumns(Value value) {
		for ( var selectable : value.getSelectables() ) {
			if ( selectable.isFormula() ) {
				throw new MappingException( "constraint involves a formula: " + name );
			}
			else {
				addColumn( (Column) selectable );
			}
		}
	}

	/**
	 * @return true if this constraint already contains a column with same name.
	 */
	public boolean containsColumn(Column column) {
		return columns.contains( column );
	}

	public int getColumnSpan() {
		return columns.size();
	}

View on GitHub (pinned to fad1729dce)

Solutions

Map constrained parts (id members, PK columns, unique key members) to real database columns instead of formulas.
Move the formula-derived value out of the constrained component into a normal read-only property.
If uniqueness must be enforced on a computed value, use a database generated column plus a real constraint.

Example fix

<!-- before -->
<composite-id name="id" class="com.acme.CompId">
    <key-property name="code"/>
    <key-property name="derived" formula="upper(code)"/>
</composite-id>

<!-- after -->
<composite-id name="id" class="com.acme.CompId">
    <key-property name="code"/>
    <key-property name="derived" column="derived_col"/>
</composite-id>

Defensive patterns

Strategy: try-catch

Try / catch

try {
    metadata = sources.buildMetadata();
} catch (MappingException e) {
    // message contains the constraint name - locate it in the mappings
    // and check its members for @Formula / <formula> parts
    throw e;
}

Prevention

Never reference @Formula-mapped properties inside ids, @EmbeddedId classes, or unique constraint definitions.
Review any <formula> elements inside hbm <composite-id>, <properties>, or key mappings.
Generate DDL in CI (create then drop) so invalid constraints fail the build.

When it happens

Trigger: A composite id containing a formula-mapped part (hbm <key-property formula="..."> or a formula inside the id value); a unique key declared over properties where one is mapped with @Formula; an association used as id or in a unique constraint where part of the join comes from @JoinColumnOrFormula's formula side.

Common situations: Using @Formula for derived values and then referencing those values in ids or unique constraints; legacy hbm mappings mixing <column> and <formula> inside constrained elements; trying to enforce uniqueness on a read-only computed field.

Related errors

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