hibernate/hibernate-orm · error · UnknownPathException

Path '<navigablePath>' did not reference a known model part

Error message

Path '<navigablePath>' did not reference a known model part

What it means

During SQM-to-SQL translation, BasicValuedPathInterpretation tries to map a basic-valued path to a column of the surrounding table group. When the path resolves in SQM but no model part (column) is found on the table group - typically a subclass or secondary-table attribute without the necessary join/treat - it throws UnknownPathException('Path ... did not reference a known model part'), unless strict-JPA mode first converts the diagnosis to an implicit-treat violation. It means the query parsed fine but has no SQL-level meaning for that path.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/sqm/sql/internal/BasicValuedPathInterpretation.java:113

						.resolveSqlExpression( tableReference, mapping );
		return new BasicValuedPathInterpretation<>( columnReference( expression ), navigablePath, mapping, tableGroup );
	}

	private static <T> void modelPartError(
			SqmBasicValuedSimplePath<T> sqmPath,
			boolean jpaQueryComplianceEnabled,
			TableGroup tableGroup) {
		if ( jpaQueryComplianceEnabled ) {
			// to get the better error, see if we got nothing because of treat handling
			final var subPart =
					tableGroup.getModelPart()
							.findSubPart( sqmPath.getReferencedPathSource().getPathName(), null );
			if ( subPart != null ) {
				throw new StrictJpaComplianceViolation( StrictJpaComplianceViolation.Type.IMPLICIT_TREAT );
			}
		}

		throw new UnknownPathException( "Path '" + sqmPath.getNavigablePath() + "' did not reference a known model part" );
	}

	private static ColumnReference columnReference(Expression expression) {
		if ( expression instanceof ColumnReference reference ) {
			return reference;
		}
		else if ( expression instanceof SqlSelectionExpression selection ) {
			final var selectedExpression = selection.getSelection().getExpression();
			assert selectedExpression instanceof ColumnReference;
			return (ColumnReference) selectedExpression;
		}
		else {
			throw new UnsupportedOperationException( "Unsupported basic-valued path expression : " + expression );
		}
	}

	private final ColumnReference columnReference;
	private final @Nullable String affectedTableName;

View on GitHub (pinned to fad1729dce)

Solutions

1. Force the join explicitly: join the subtype/secondary entity or use TREAT(p AS Sub).attr so the table group includes the needed table
2. Query the concrete subtype entity instead of the polymorphic base
3. If strict compliance produced this instead of the implicit-treat error, make the treat explicit (treat(p as Sub).attr) or turn off strict compliance after reviewing portability
4. Re-check inheritance mapping (@Inheritance(strategy=JOINED)) and attribute placement after refactorings - move the attribute to the class whose table is always present or accept explicit joins

Example fix

-- before
select p.bonus from Person p   -- bonus lives in Employee table (JOINED)
-- after
select treat(p as Employee).bonus from Person p
-- or
from Employee e select e.bonus

// Before executing, ensure subclass/secondary fields are reached through treat
String hql = query.trim();
Set<String> subclassOnlyFields = Set.of("bonus"); // maintained list
if (subclassOnlyFields.stream().anyMatch(hql::contains)) {
    hql = hql.replace("p.bonus", "treat(p as Employee).bonus");
}

static boolean pathNeedsTreat(EntityManager em, Class<?> base, String attr) {
    try { em.getMetamodel().entity(base).getAttribute(attr); return false; }
    catch (IllegalArgumentException e) { return true; }
}

catch (UnknownPathException e) { /* log navigablePath from message, add explicit join/treat, or fall back to subtype-specific query */ }

When it happens

Trigger: HQL referencing a joined-subclass or secondary-table attribute on an alias whose table group only covers the base table (e.g. 'select p.secondaryField from Base p' without a treat that forces the join); queries on inheritance strategies (JOINED, table-per-class) where the attribute physically lives in another table; interactions between implicit subtyping and @Fetch/JOIN mapping overrides that drop the needed table reference.

Common situations: Polymorphic HQL written against a base alias after inheritance mapping was refactored to JOINED; disabling implicit treats; upgrading Hibernate 5 -> 6/7 where legacy alias-to-table linking was replaced by strict table-group resolution; secondary tables (@SecondaryTable/@OneToOne joined) whose join is not triggered because the attribute is only referenced in select under certain fetch modes.

Related errors

• Not expecting multiple table references for an SQM INSERT-SE
• Entity discriminator cannot be de-referenced
• Could not resolve attribute '%s' of '%s' due to the attribut
• Discriminator formulas on joined inheritance hierarchies not
• Basic-value cannot be treated (downcast)

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