{"record":{"id":"8395d55389b1afa8","repo":"hibernate/hibernate-orm","slug":"could-not-resolve-named-query-for-loading-col","errorCode":null,"errorMessage":"Could not resolve named query '{}' for loading collection '{}'","messagePattern":"Could not resolve named query '(.+?)' for loading collection '(.+?)'","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/persister/collection/AbstractCollectionPersister.java","lineNumber":747,"sourceCode":"\n\t\t// Build collection table descriptor\n\t\t// For one-to-many collections, this represents the element entity's table\n\t\t// For other collection types, this represents the collection table\n\t\tcollectionTableDescriptor = buildCollectionTableDescriptor(\n\t\t\t\ttableMapping,\n\t\t\t\tattributeMapping,\n\t\t\t\tfactory\n\t\t);\n\n\t\tlogStaticSQL();\n\t}\n\n\tprivate NamedQueryMemento<?> getNamedQueryMemento(MetadataImplementor bootModel) {\n\t\tfinal var memento =\n\t\t\t\tfactory.getQueryEngine().getNamedObjectRepository()\n\t\t\t\t\t\t.resolve( factory, bootModel, queryLoaderName );\n\t\tif ( memento == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Could not resolve named query '\" + queryLoaderName\n\t\t\t\t\t+ \"' for loading collection '\" + getRole() + \"'\" );\n\t\t}\n\t\treturn memento;\n\t}\n\n\tprotected void logStaticSQL() {\n\t\tif ( MODEL_MUTATION_LOGGER.isTraceEnabled() ) {\n\t\t\tMODEL_MUTATION_LOGGER.staticSqlForCollection( getRole() );\n\n\t\t\tfinal var rowMutationOperations = getRowMutationOperations();\n\n\t\t\tfinal var insertRowOperation = rowMutationOperations.getInsertRowOperation();\n\t\t\tfinal String insertRowSql = insertRowOperation != null ? insertRowOperation.getSqlString() : null;\n\t\t\tif ( insertRowSql != null ) {\n\t\t\t\tMODEL_MUTATION_LOGGER.collectionRowInsert( insertRowSql );\n\t\t\t}\n\n\t\t\tfinal var updateRowOperation = rowMutationOperations.getUpdateRowOperation();","sourceCodeStart":729,"sourceCodeEnd":765,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/persister/collection/AbstractCollectionPersister.java#L729-L765","documentation":"When a collection is mapped with a named-query loader (@Loader(namedQuery=...) or hbm.xml <loader query-name=...>), AbstractCollectionPersister.getNamedQueryMemento resolves that name against the QueryEngine's NamedObjectRepository; a null result throws IllegalArgumentException naming the missing query and the collection role. This happens during SessionFactory initialization, before any session use.","triggerScenarios":"A collection annotated @Loader(namedQuery=\"x\") with no @NamedQuery(name=\"x\") defined anywhere in the persistence unit; the query lives in orm.xml or another class not scanned; a typo or rename of the query name; the loader is defined for a collection whose query was removed.","commonSituations":"Custom loaders introduced for tuning, then the query is renamed or deleted; query defined in a different module's orm.xml that is not included in the PU; case-sensitive mismatch between @Loader(namedQuery) and @NamedQuery(name).","solutions":["Define a @NamedQuery (or orm.xml <named-query>) with exactly the name referenced by @Loader(namedQuery=...), in the same persistence unit","Fix typos/casing in the loader name to match the registered query name","Remove the @Loader from the collection if the custom loading query is no longer needed"],"exampleFix":"// before\n@OneToMany(mappedBy = \"order\")\n@Loader(namedQuery = \"loadOrderLines\") // no matching named query -> IllegalArgumentException\nprivate List<OrderLine> lines;\n\n// after\n@NamedQuery(name = \"loadOrderLines\",\n  query = \"select l from OrderLine l where l.order.id = :id\")\n@OneToMany(mappedBy = \"order\")\n@Loader(namedQuery = \"loadOrderLines\")\nprivate List<OrderLine> lines;","handlingStrategy":"validation","validationCode":"// Startup scan: every @Loader(namedQuery=...) must match a declared @NamedQuery in the same PU\nSet<String> namedQueries = new HashSet<>();\nfor (Class<?> c : scannedEntityClasses) {\n  for (jakarta.persistence.NamedQuery q : c.getAnnotationsByType(jakarta.persistence.NamedQuery.class)) {\n    namedQueries.add(q.name());\n  }\n}\nfor (Class<?> c : scannedEntityClasses) {\n  for (java.lang.reflect.Field f : c.getDeclaredFields()) {\n    org.hibernate.annotations.Loader loader = f.getAnnotation(org.hibernate.annotations.Loader.class);\n    if (loader != null && !namedQueries.contains(loader.namedQuery())) {\n      throw new IllegalStateException(\"@Loader(namedQuery='\" + loader.namedQuery()\n          + \"') on \" + f + \" has no matching @NamedQuery\");\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  sessionFactory = new Configuration().addAnnotatedClass(Order.class).buildSessionFactory();\n} catch (IllegalArgumentException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"Could not resolve named query\")) {\n    throw new IllegalStateException(\"Collection loader references a missing @NamedQuery — define it or fix the name\", e);\n  }\n  throw e;\n}","preventionTips":["Define the loader @NamedQuery on the same class (or orm.xml) as the collection it loads","Rename @NamedQuery names and their @Loader references together","Include orm.xml queries in the validation scan — annotation-only checks miss XML-declared queries"],"tags":["hibernate","named-query","loader","collection-mapping","bootstrap"],"backgroundTag":"named-query-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}