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.

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.

Appendix: 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)