hibernate/hibernate-orm · error · MappingException

Expecting just a single formula/column in context of <%s nam

Error message

Expecting just a single formula/column in context of <%s name="%s"/>

What it means

RelationalValueSourceHelper.buildValueSource serves mappings that accept exactly one column or one formula (for example <discriminator/>, <version/>, <timestamp/> style single-valued elements). When the mapping yields more than one RelationalValueSource - two <column> children, or a multi-entry column attribute - bootstrap fails with this message interpolating the element name and its name attribute.

Source

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

	 *
	 * @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 single RelationalValueSource.
	 */
	public static RelationalValueSource buildValueSource(
			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() );
		}

		return sources.get( 0 );
	}

	/**
	 * Given a {@link ColumnsAndFormulasSource}, build a single {@link RelationalValueSource}
	 * which is required to be a column.  More than one {@link RelationalValueSource} will result
	 * in an exception.  A 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 single ColumnSource.
	 */
	public static ColumnSource buildColumnSource(
			MappingDocument mappingDocument,

View on GitHub (pinned to fad1729dce)

Solutions

1. Reduce the element named in the message to exactly one <column> or one <formula>
2. If the value genuinely spans several columns, this element cannot map it - restructure as a composite (<component>/<properties>) mapping
3. Check for accidental duplicate <column> children introduced by copy-paste or code generation

Example fix

// before
<discriminator>
    <column name='dtype_a'/>
    <column name='dtype_b'/>
</discriminator>

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

// Pre-flight: single-valued elements (<discriminator>, <version>, <timestamp>, <collection-id>) accept at most one column/formula
for (String tag : new String[]{"discriminator", "version", "timestamp", "collection-id"}) {
    var e = (org.w3c.dom.Element) doc.getElementsByTagName(tag).item(0);
    if (e == null) continue;
    int n = e.getElementsByTagName("column").getLength() + e.getElementsByTagName("formula").getLength();
    if (n > 1 || e.getAttribute("column").contains(","))
        throw new IllegalStateException(tag + " accepts exactly one column/formula");
}

catch (org.hibernate.boot.MappingException e) at Metadata build: the message names the element and its name attribute - reduce that element to a single <column> or <formula>

When it happens

Trigger: A single-valued mapping element lists multiple relational values, e.g. <discriminator> with two <column> children, or a comma-separated column='a,b' style attribute expanding to two values on an element handled by buildValueSource.

Common situations: Attempting a composite discriminator (not supported); splitting one logical column into two <column> halves; mappings carried over from tools that emit multiple column elements for every value.

Related errors

• Expecting single column in context of <%s name="%s"/>, but f
• column attribute may not be specified along with <column/> o
• Encountered unexpected content type [%s] for named native qu
• <many-to-any /> mapping [%s] needs to specify 2 or more colu
• <many-to-any /> mapping [%s] needs to specify 2 or more colu

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