hibernate/hibernate-orm · error · MappingException

Expecting single column in context of <%s name="%s"/>, but f

Error message

Expecting single column in context of <%s name="%s"/>, but found formula [%s]

What it means

After buildColumnSource narrows a mapping to exactly one relational value, that value must be a ColumnSource. If the single source is a DerivedValueSource - a <formula> element or formula='...' attribute - Hibernate throws this message echoing the element, its name and the formula expression. The mapping position requires a physical column; derived values are not accepted here (unlike regular <property> mappings).

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/RelationalValueSourceHelper.java:190

			MappingDocument mappingDocument,
			String containingTableName,
			ColumnsAndFormulasSource columnsAndFormulasSource) {
		final List<RelationalValueSource> sources = buildValueSources(
				mappingDocument,
				containingTableName,
				columnsAndFormulasSource
		);

		if ( sources.size() > 1 ) {
			throw new MappingException( multipleError( columnsAndFormulasSource ), mappingDocument.getOrigin() );
		}

		final RelationalValueSource result = sources.get( 0 );
		if ( result instanceof ColumnSource columnSource ) {
			return columnSource;
		}
		else {
			throw new MappingException( formulaError( columnsAndFormulasSource, (DerivedValueSource) result ),
					mappingDocument.getOrigin() );
		}
	}

	/**
	 * Given a {@link ColumnsAndFormulasSource}, build the corresponding list of
	 * {@link ColumnSource}.  Any formula, rather than a column, will result in an exception.
	 *
	 * @param mappingDocument the mapping document
	 * @param containingTableName The logical name of the table containing the relational values
	 * @param columnsAndFormulasSource the adapter describing the value sources.
	 *
	 * @return The corresponding list.
	 */
	public static List<ColumnSource> buildColumnSources(
			MappingDocument mappingDocument,
			String containingTableName,
			ColumnsAndFormulasSource columnsAndFormulasSource) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Replace the formula with a physical column: <column name='...'/> backed by a real table column
2. If you also need the computed value, map it as a separate read-only <property formula='...'> alongside the required column
3. Check the Hibernate version's support for formula-based discriminators; if unsupported, use a real discriminator column

Example fix

// before
<discriminator formula="case when t = 'A' then 'TYPE_A' else 'TYPE_B' end"/>

// after
<discriminator column='dtype'/>

// Pre-flight: column-required elements must not carry a formula
var e = columnRequiredElement; // e.g. <version>, <collection-id>, <discriminator>
boolean hasFormula = e.getElementsByTagName("formula").getLength() > 0 || !e.getAttribute("formula").isEmpty();
if (hasFormula)
    throw new IllegalStateException(e.getTagName() + " requires a physical column, formulas are not allowed");

catch (org.hibernate.boot.MappingException e) at Metadata build: the message echoes the offending formula - replace it with a real column and, if still needed, map the expression as a separate read-only <property formula='...'>

When it happens

Trigger: Supplying a formula where exactly one column is required: e.g. a <version formula='...'/> or <collection-id> built through a <formula> element on a mapping handled by buildColumnSource. The printed formula text is the derived expression that was found.

Common situations: Wanting a computed discriminator or version value; migrating a mapping that used a formula where the current Hibernate version now demands a real column; not realizing which elements accept formulas (plain <property> does, these single-column elements do not).

Related errors

• Expecting just a single formula/column in context of <%s nam
• formula attribute may not be specified along with <column/>
• column attribute may not be specified along with <column/> o
• Identifier property '" + getPath( holder, data ) + "' cannot
• Encountered unexpected content type [%s] for named native qu

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