What causes "unsupported temporal unit for CUBRID: " + unit" in hibernate/hibernate-orm?

Ensure the association containing the column is actually joined in the query (HQL 'join fetch' / explicit join, criteria .join()) rather than referenced implicitly.

hibernate/hibernate-orm · error · SemanticException

unsupported temporal unit for CUBRID: " + unit

Error message

unsupported temporal unit for CUBRID: " + unit

What it means

resolveTableReference(navigablePath, tableExpression) asks a from-clause element (table group/reference) for the physical TableReference of a given table name and throws UnknownTableReferenceException when lookup returns null. Concretely: a column is about to be rendered against a table that this from-element does not contain - typically a secondary table, a subclass table, or the wrong side of an association that was never joined.

Source

Thrown at hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/CUBRIDDialect.java:574

				timediff(pattern, MINUTE, unit);
				pattern.append("+");
				timediff(pattern, HOUR, unit);
				pattern.append(")");
				break;
			case NATIVE:
			case NANOSECOND:
				pattern.append("(");
				timediff(pattern, unit, unit);
				pattern.append("+");
				timediff(pattern, SECOND, unit);
				pattern.append("+");
				timediff(pattern, MINUTE, unit);
				pattern.append("+");
				timediff(pattern, HOUR, unit);
				pattern.append(")");
				break;
			default:
				throw new SemanticException("unsupported temporal unit for CUBRID: " + unit);
		}
		return pattern.toString();
	}

	private void timediff(
			StringBuilder sqlAppender,
			TemporalUnit diffUnit,
			TemporalUnit toUnit) {
		if ( diffUnit == NANOSECOND ) {
			sqlAppender.append("1e6*");
		}
		sqlAppender.append("extract(");
		if ( diffUnit == NANOSECOND || diffUnit == NATIVE ) {
			sqlAppender.append("millisecond");
		}
		else {
			sqlAppender.append("?1");
		}

View on GitHub (pinned to fad1729dce)

Solutions

Ensure the association containing the column is actually joined in the query (HQL 'join fetch' / explicit join, criteria .join()) rather than referenced implicitly.
Query the concrete subclass or an entity type that actually maps the table named in the message.
Fix the mapping so the attribute is mapped to a table that is part of the queried table group (e.g. move the column, adjust @SecondaryTable usage).
Check custom table-group/persister code if present, then upgrade Hibernate - several UnknownTableReferenceException paths were fixed across 6.x/7.x.

Example fix

// before: implicit reference to a table never joined
"select o from Order o where o.customer.vipCard.number is null" // vipCard table not joined

// after: explicit join so the table group contains the table
"select o from Order o join fetch o.customer c left join fetch c.vipCard v where v.number is null"

Defensive patterns

Strategy: try-catch

Try / catch

try {
    return em.createQuery(hql, type).getResultList();
} catch ( UnknownTableReferenceException e ) {
    // message: "Unable to determine TableReference (`tbl`) for `path`"
    // add an explicit join for the association owning `tbl`, then retry
    return em.createQuery(withExplicitJoin(hql, e.getTableExpression()), type).getResultList();
}

Prevention

Always join (or join-fetch) associations whose columns you reference - do not rely on implicit resolution across secondary/subclass tables.
Run the full query suite on the production dialect; table-reference resolution differs by dialect path.
After moving columns between tables, grep queries and DTOs for the old attribute paths.
Keep Hibernate current - UnknownTableReferenceException paths get fixed across point releases.

When it happens

Trigger: Resolving a column whose mapped table is absent from the current table group: secondary-table (@SecondaryTable) columns on a join path that skipped the secondary table; subclass-specific tables in TABLE_PER_CLASS/union contexts; @ManyToOne target columns resolved without the target table joined; paths crossing a one-to-one mappedBy group; locking or native operations on derived mappings.

Common situations: Migrating apps to Hibernate 6/7 where secondary-table and inheritance resolution became stricter; criteria queries on a superclass selecting subclass-only attributes; queries touching the inverse side of one-to-one relations; mapping refactors where a column moved to another table while queries still ran.

Related errors

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