What causes "unrecognized field: " + unit" in hibernate/hibernate-orm?

Ensure every selectable of the function-backed embeddable resolves through the function reference itself - pass its own tableExpression, not a base-table name.

hibernate/hibernate-orm · error · SemanticException

unrecognized field: " + unit

Error message

unrecognized field: " + unit

What it means

EmbeddableFunctionTableReference is the from-element for an embeddable backed by a table-valued SQL function; its only 'table' is the function's table expression. resolveTableReference returns itself for that one expression and throws UnknownTableReferenceException for any other name - meaning translation asked a function-backed embeddable for a named table it cannot possibly provide.

Source

Thrown at hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/CockroachLegacyDialect.java:944

					case DAY:
						return "extract(day from ?3-?2)";
					//in order to avoid multiple calls to extract(),
					//we use extract(epoch from x - y) * factor for
					//all the following units:

					// Note that CockroachDB also has an extract_duration function which returns an int,
					// but we don't use that here because it is deprecated since v20.
					// We need to use round() instead of cast(... as int) because extract epoch returns
					// float8 which can cause loss-of-precision in some cases
					// https://github.com/cockroachdb/cockroach/issues/72523
					case HOUR:
					case MINUTE:
					case SECOND:
					case NANOSECOND:
					case NATIVE:
						return "round(extract(epoch from ?3-?2)" + EPOCH.conversionFactor( unit, this ) + ")::int";
					default:
						throw new SemanticException( "unrecognized field: " + unit );
				}
			}
			else {
				switch (unit) {
					case YEAR:
						return "extract(year from ?3-?2)";
					case QUARTER:
						return "(extract(year from ?3-?2)*4+extract(month from ?3-?2)//3)";
					case MONTH:
						return "(extract(year from ?3-?2)*12+extract(month from ?3-?2))";
					// Prior to v20, Cockroach didn't support extracting from an interval/duration,
					// so we use the extract_duration function
					case WEEK:
						return "extract_duration(hour from ?3-?2)/168";
					case DAY:
						return "extract_duration(hour from ?3-?2)/24";
					case NANOSECOND:
						return "extract_duration(microsecond from ?3-?2)*1e3";

View on GitHub (pinned to fad1729dce)

Solutions

Ensure every selectable of the function-backed embeddable resolves through the function reference itself - pass its own tableExpression, not a base-table name.
Align the mapping so paths into that embeddable never need secondary/subclass tables.
Fix custom dialect/function table reference implementations to keep a single consistent table expression.
Upgrade Hibernate; report with the function mapping if core code requested the wrong expression.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    return query.getResultList();
} catch ( UnknownTableReferenceException e ) {
    // log the requested table expression vs the function reference's own tableExpression
    LOG.warn("Function-table mismatch: {}", e.getMessage());
    throw e; // needs mapping/code fix, not a runtime retry
}

Prevention

Keep exactly one table expression for function-backed embeddables and resolve all their selectables through it.
In custom dialect function-table code, never mix named base tables into paths rooted at a function reference.
Add a unit test asserting resolveTableReference(fnTableExpression) succeeds and foreign names fail loudly during development, not in production.

When it happens

Trigger: SQL AST resolution requesting a table expression different from the function's tableExpression on an embeddable mapped to a table-valued function - typically when custom dialect/function table references are mixed with named-table resolution, or when a path into the embeddable is resolved with a secondary/subclass table name.

Common situations: Custom table-valued-function mappings (@TableFunctionTable? / function table references) after refactors that changed table expressions; dialect extension code; Hibernate version changes in how embeddable function tables expose names.

Related errors

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