{"record":{"id":"1bd3775f1e3a8e76","repo":"hibernate/hibernate-orm","slug":"unknown-query-type-for-registering-as-named-query","errorCode":null,"errorMessage":"Unknown query type for registering as named query (%s) : %s","messagePattern":"Unknown query type for registering as named query \\((.+?)\\) : (.+?)","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java","lineNumber":1181,"sourceCode":"\n\t@Override\n\tpublic void addNamedQuery(@Nonnull String name, @Nonnull Query query) {\n\t\tif ( query instanceof TypedQuery<?> typedQuery ) {\n\t\t\taddNamedQuery( name, typedQuery );\n\t\t}\n\t\telse if ( query instanceof Statement statement ) {\n\t\t\taddNamedStatement( name, statement );\n\t\t}\n\t\telse if ( query instanceof MutationOrSelectionQuery statementOrTypedQuery ) {\n\t\t\tif ( statementOrTypedQuery.isMutationQuery() ) {\n\t\t\t\taddNamedStatement( name, statementOrTypedQuery.asMutationQuery() );\n\t\t\t}\n\t\t\telse {\n\t\t\t\taddNamedQuery( name, statementOrTypedQuery.asSelectionQuery() );\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\tthrow new HibernateException( String.format( ROOT,\n\t\t\t\t\t\"Unknown query type for registering as named query (%s) : %s\",\n\t\t\t\t\tname,\n\t\t\t\t\tquery\n\t\t\t) );\n\t\t}\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic <R> TypedQueryReference<R> addNamedQuery(@Nonnull String name, @Nonnull TypedQuery<R> query) {\n\t\treturn getNamedObjectRepository().registerNamedQuery( name, query );\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic StatementReference addNamedStatement(@Nonnull String name, @Nonnull Statement statement) {\n\t\treturn getNamedObjectRepository().registerNamedMutation( name, statement );\n\t}","sourceCodeStart":1163,"sourceCodeEnd":1199,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java#L1163-L1199","documentation":"When registering an existing query object as a named query, Hibernate's runtime dispatch only accepts org.hibernate.query.Statement / MutationOrSelectionQuery implementations — i.e. query objects created by the same Hibernate factory. Any other TypedQuery implementation (another JPA provider's, a wrapper, a mock) falls through the instanceof chain and triggers HibernateException 'Unknown query type'.","triggerScenarios":"Calling sessionFactory.addNamedQuery(name, typedQuery) where the TypedQuery was not produced by this Hibernate SessionFactory: a query from a different JPA provider, a delegating wrapper TypedQuery, or a stub in tests. Also passing a StoredProcedureQuery or custom TypedQuery subtype.","commonSituations":"Multi-provider code or abstraction layers (e.g. a generic DAO) that mix vendor query objects; unit tests registering Mockito mocks of TypedQuery; frameworks that wrap queries for instrumentation/tenancy and then try to re-register the wrapper.","solutions":["Register a query created by the same factory: rebuild it via sessionFactory.createSelectionQuery(...)/createMutationQuery(...) and register that","If you hold a wrapped query, unwrap to the Hibernate type first: query.unwrap(org.hibernate.query.Query.class)","For selection vs mutation, branch on instanceof SelectionQuery/MutationQuery and pass the unwrapped Statement form","In tests, register a real query built from a test EMF instead of a mock"],"exampleFix":"// before\ntypedQuery = wrapForMetrics(em.createQuery(jpql));\nsessionFactory.addNamedQuery(\"findAll\", typedQuery); // wrapper is not a Statement -> throws\n\n// after\norg.hibernate.query.SelectionQuery<Order> hq =\n        sessionFactory.createSelectionQuery(jpql, Order.class);\nsessionFactory.addNamedQuery(\"findAll\", hq);","handlingStrategy":"type-guard","validationCode":"if (query instanceof org.hibernate.query.SelectionQuery<?> sq) {\n    sessionFactory.addNamedQuery(name, sq);\n} else if (query instanceof org.hibernate.query.MutationQuery mq) {\n    sessionFactory.addNamedQuery(name, mq);\n} else {\n    throw new IllegalArgumentException(\"Query is not a Hibernate Statement: \" + query.getClass());\n}","typeGuard":"static boolean isRegistrable(TypedQuery<?> q) {\n    return q instanceof org.hibernate.query.Statement;\n}","tryCatchPattern":"try {\n    sessionFactory.addNamedQuery(name, typedQuery);\n} catch (HibernateException e) {\n    if (e.getMessage().contains(\"Unknown query type\")) {\n        // re-create the query from this factory and register that instead\n        var rebuilt = sessionFactory.createSelectionQuery(jpql, resultClass);\n        sessionFactory.addNamedQuery(name, rebuilt);\n    } else throw e;\n}","preventionTips":["Only register query objects produced by the same SessionFactory","Unwrap decorated queries to org.hibernate.query.Query before registering","In tests, build real queries from a test EMF instead of mocking TypedQuery"],"tags":["hibernate","named-query","query","api-misuse","instanceof-dispatch"],"backgroundTag":"unsupported-argument-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}