{"record":{"id":"e9c83687881cc929","repo":"hibernate/hibernate-orm","slug":"unknown-entity-type-e9c836","errorCode":null,"errorMessage":"Unknown entity type '{}'","messagePattern":"Unknown entity type '(.+?)'","errorType":"exception","errorClass":"UnknownEntityTypeException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/internal/AbstractSharedSessionContract.java","lineNumber":1965,"sourceCode":"\t\t\t\t\t: null,\n\t\t\t\tresultClass\n\t\t);\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic <T> NativeQueryImplementor<T> createNativeQuery(\n\t\t\t@Nonnull String sqlString,\n\t\t\t@Nonnull Class<T> resultClass,\n\t\t\t@Nonnull String tableAlias) {\n\t\tchecksBeforeQueryCreation();\n\t\tfinal var query = buildNativeQuery( sqlString, null, resultClass );\n\t\tif ( getMappingMetamodel().isEntityClass( resultClass ) ) {\n\t\t\tquery.addEntity( tableAlias, resultClass, LockMode.READ );\n\t\t\treturn query;\n\t\t}\n\t\telse {\n\t\t\tthrow new UnknownEntityTypeException( resultClass );\n\t\t}\n\t}\n\n\tprivate <T> NativeQueryImpl<T> buildNativeQuery(\n\t\t\tString sql,\n\t\t\t@Nullable NamedResultSetMappingMemento resultSetMapping,\n\t\t\t@Nullable Class<T> resultClass) {\n\t\ttry {\n\t\t\tfinal var query = new NativeQueryImpl<>( sql, resultSetMapping, resultClass, this );\n\t\t\tif ( isEmpty( query.getComment() ) ) {\n\t\t\t\tquery.setComment( \"dynamic native SQL query\" );\n\t\t\t}\n\t\t\tapplyQuerySettingsAndHints( query );\n\t\t\treturn query;\n\t\t}\n\t\tcatch ( RuntimeException he ) {\n\t\t\tthrow getExceptionConverter().convert( he );\n\t\t}","sourceCodeStart":1947,"sourceCodeEnd":1983,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/AbstractSharedSessionContract.java#L1947-L1983","documentation":"The three-argument createNativeQuery(sql, resultClass, tableAlias) overload has entity semantics: it binds resultClass as a mapped entity under the alias (addEntity(alias, resultClass, LockMode.READ)). getMappingMetamodel().isEntityClass(resultClass) is false for DTOs, records, interfaces, and mapped superclasses, so UnknownEntityTypeException('Unknown entity type <class>') is thrown.","triggerScenarios":"createNativeQuery(sql, CustomerDto.class, \"c\") where CustomerDto is a projection DTO; passing a base class or @MappedSuperclass of the entity; interface-typed results — anything that is not a registered @Entity in the mapping metamodel.","commonSituations":"Switching a two-argument native DTO query to the three-arg form after an IDE suggestion or Hibernate 5 addEntity-style port; projection interfaces/records used with the alias overload; inheritance hierarchies queried with the root abstract class.","solutions":["For DTO projections drop the alias argument: createNativeQuery(sql, CustomerDto.class) — Hibernate maps columns to the DTO by position/name.","If you meant an entity, pass the mapped @Entity class (the concrete leaf for inheritance).","Alternatively define the mapping explicitly with @SqlResultSetMapping and use the mapping-name overload."],"exampleFix":"// before\nNativeQuery<CustomerDto> q = session.createNativeQuery(\n    \"select id, name from customer c\", CustomerDto.class, \"c\"); // UnknownEntityTypeException\n// after (DTO projection: two-arg form)\nNativeQuery<CustomerDto> q = session.createNativeQuery(\n    \"select id, name from customer\", CustomerDto.class);","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"static boolean isMappedEntity(SessionFactory sf, Class<?> type) {\n    return sf.getMetamodel().getEntities().stream()\n             .anyMatch(e -> type.equals(e.getJavaType()));\n}\n\n// usage: choose the right native-query overload\nif (isMappedEntity(sf, resultClass)) {\n    return session.createNativeQuery(sql, resultClass, alias); // entity binding\n} else {\n    return session.createNativeQuery(sql, resultClass);         // DTO projection\n}","tryCatchPattern":null,"preventionTips":["Reserve the three-argument native-query overload for mapped @Entity classes","Keep DTO projections on the two-argument form","When using interfaces or mapped superclasses, load the concrete entity class instead"],"tags":["hibernate","native-query","dto","entity-mapping","projection"],"backgroundTag":"unknown-entity-mapping","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}