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

Start the query from the owning entity so model parts resolve against its own table group.

hibernate/hibernate-orm · error · UnsupportedOperationException

Unsupported unit: " + unit

Error message

Unsupported unit: " + unit

What it means

The model-part-aware resolveTableReference on MappedByTableGroup: identical semantics to the string variant but triggered when the requested ValuedModelPart's table expression cannot be provided by the underlying mapped-by table group. It marks a mismatch between where a part's columns live (owning side / secondary table) and what the inverse-side group can resolve.

Source

Thrown at hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/DB2LegacyDialect.java:703

				}
				else {
					return "(select (days(t2)-days(t1))*24+(midnight_seconds(t2)-midnight_seconds(t1))/3600 " +
						"from lateral(values(" + fromExpression + ',' + toExpression + ")) as temp(t1,t2))";
				}
			case YEAR:
				return "(year(" + toExpression + ")-year(" + fromExpression + "))";
			// the months_between() function results
			// in a non-integral value, so trunc() it
			case MONTH:
				return "trunc(months_between(" + toExpression + ',' + fromExpression + "))";
			case QUARTER:
				return "trunc(months_between(" + toExpression + ',' + fromExpression + ")/3)";
			case WEEK:
				return "int((days" + toExpression + ")-days(" + fromExpression + "))/7)";
			case DAY:
				return "(days(" + toExpression + ")-days(" + fromExpression + "))";
			default:
				throw new UnsupportedOperationException( "Unsupported unit: " + unit );
		}
	}

	@Override
	public String timestampaddPattern(TemporalUnit unit, TemporalType temporalType, IntervalType intervalType) {
		final StringBuilder pattern = new StringBuilder();
		final String timestampExpression;
		if ( unit.isDateUnit() ) {
			if ( temporalType == TemporalType.TIME ) {
				timestampExpression = "timestamp('1970-01-01',?3)";
			}
			else {
				timestampExpression = "?3";
			}
		}
		else {
			if ( temporalType == TemporalType.DATE ) {
				timestampExpression = "cast(?3 as timestamp)";

View on GitHub (pinned to fad1729dce)

Solutions

Start the query from the owning entity so model parts resolve against its own table group.
Make the frequently-queried direction the owning side of the association.
Add explicit joins for the owning entity where its columns are needed.
Upgrade to the latest Hibernate 7.x and report persistent cases to HHH.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    return query.getResultList();
} catch ( UnknownTableReferenceException e ) {
    // model-part table not reachable via mapped-by group: join the owning entity explicitly
    return em.createQuery(withOwnerJoin(hql), type).getResultList();
}

Prevention

Add explicit joins to the owning entity before referencing its columns from the inverse side.
Avoid secondary tables and JOINED inheritance on entities that are frequent mappedBy targets.
Re-run one-to-one inverse-path queries after each Hibernate upgrade; resolution there changes between versions.

When it happens

Trigger: Model-part column resolution (fk parts, embedded parts, id parts) during criteria/HQL translation while the current table group is a one-to-one mappedBy group that lacks the owning-side table; subclass or secondary-table parts of the owner resolved through the inverse.

Common situations: Polymorphic queries over one-to-one inverses; @OneToOne(mappedBy) with secondary tables or JOINED inheritance on the owner; post-upgrade regressions in inverse-side resolution.

Related errors

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