{"record":{"id":"5c15a0ad05a84e96","repo":"hibernate/hibernate-orm","slug":"path-navigablepath-did-not-reference-a-known-m","errorCode":null,"errorMessage":"Path '<navigablePath>' did not reference a known model part","messagePattern":"Path '<navigablePath>' did not reference a known model part","errorType":"exception","errorClass":"UnknownPathException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/sqm/sql/internal/BasicValuedPathInterpretation.java","lineNumber":113,"sourceCode":"\t\t\t\t\t\t.resolveSqlExpression( tableReference, mapping );\n\t\treturn new BasicValuedPathInterpretation<>( columnReference( expression ), navigablePath, mapping, tableGroup );\n\t}\n\n\tprivate static <T> void modelPartError(\n\t\t\tSqmBasicValuedSimplePath<T> sqmPath,\n\t\t\tboolean jpaQueryComplianceEnabled,\n\t\t\tTableGroup tableGroup) {\n\t\tif ( jpaQueryComplianceEnabled ) {\n\t\t\t// to get the better error, see if we got nothing because of treat handling\n\t\t\tfinal var subPart =\n\t\t\t\t\ttableGroup.getModelPart()\n\t\t\t\t\t\t\t.findSubPart( sqmPath.getReferencedPathSource().getPathName(), null );\n\t\t\tif ( subPart != null ) {\n\t\t\t\tthrow new StrictJpaComplianceViolation( StrictJpaComplianceViolation.Type.IMPLICIT_TREAT );\n\t\t\t}\n\t\t}\n\n\t\tthrow new UnknownPathException( \"Path '\" + sqmPath.getNavigablePath() + \"' did not reference a known model part\" );\n\t}\n\n\tprivate static ColumnReference columnReference(Expression expression) {\n\t\tif ( expression instanceof ColumnReference reference ) {\n\t\t\treturn reference;\n\t\t}\n\t\telse if ( expression instanceof SqlSelectionExpression selection ) {\n\t\t\tfinal var selectedExpression = selection.getSelection().getExpression();\n\t\t\tassert selectedExpression instanceof ColumnReference;\n\t\t\treturn (ColumnReference) selectedExpression;\n\t\t}\n\t\telse {\n\t\t\tthrow new UnsupportedOperationException( \"Unsupported basic-valued path expression : \" + expression );\n\t\t}\n\t}\n\n\tprivate final ColumnReference columnReference;\n\tprivate final @Nullable String affectedTableName;","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/sqm/sql/internal/BasicValuedPathInterpretation.java#L95-L131","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Force the join explicitly: join the subtype/secondary entity or use TREAT(p AS Sub).attr so the table group includes the needed table","Query the concrete subtype entity instead of the polymorphic base","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","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"],"exampleFix":"-- before\nselect p.bonus from Person p   -- bonus lives in Employee table (JOINED)\n-- after\nselect treat(p as Employee).bonus from Person p\n-- or\nfrom Employee e select e.bonus","handlingStrategy":"try-catch","validationCode":"// Before executing, ensure subclass/secondary fields are reached through treat\nString hql = query.trim();\nSet<String> subclassOnlyFields = Set.of(\"bonus\"); // maintained list\nif (subclassOnlyFields.stream().anyMatch(hql::contains)) {\n    hql = hql.replace(\"p.bonus\", \"treat(p as Employee).bonus\");\n}","typeGuard":"static boolean pathNeedsTreat(EntityManager em, Class<?> base, String attr) {\n    try { em.getMetamodel().entity(base).getAttribute(attr); return false; }\n    catch (IllegalArgumentException e) { return true; }\n}","tryCatchPattern":"catch (UnknownPathException e) { /* log navigablePath from message, add explicit join/treat, or fall back to subtype-specific query */ }","preventionTips":["Reference secondary-table and subclass attributes only through joins or treats","After changing inheritance strategy, re-run the full HQL regression suite","Enable hibernate.query.jpa_compliance_strict in CI to catch implicit treats early"],"tags":["hibernate","hql","sqm-to-sql","unknown-path","inheritance","joined-inheritance","secondary-table"],"backgroundTag":"unknown-attribute-path","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}