{"record":{"id":"68123f9dbe646cbe","repo":"hibernate/hibernate-orm","slug":"class-or-package-level-namedquery-annotation-mu","errorCode":null,"errorMessage":"Class or package level '@NamedQuery' annotation must specify a 'name'","messagePattern":"Class or package level '@NamedQuery' annotation must specify a 'name'","errorType":"exception","errorClass":"AnnotationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryBinder.java","lineNumber":99,"sourceCode":" *\n * @author Emmanuel Bernard\n */\npublic abstract class QueryBinder {\n\tprivate static final String JAKARTA_DATA_REPOSITORY = \"jakarta.data.repository.Repository\";\n\tprivate static final String JAKARTA_DATA_QUERY = \"jakarta.data.repository.Query\";\n\tprivate static final String JAKARTA_DATA_PAGE = \"jakarta.data.page.Page\";\n\tprivate static final String JAKARTA_DATA_CURSORED_PAGE = \"jakarta.data.page.CursoredPage\";\n\n\tpublic static void bindQuery(\n\t\t\tNamedQuery namedQuery,\n\t\t\tMetadataBuildingContext context,\n\t\t\tboolean isDefault,\n\t\t\tAnnotationTarget annotationTarget) {\n\t\tif ( namedQuery != null ) {\n\t\t\tfinal String queryName = namedQuery.name();\n\t\t\tfinal String queryString = namedQuery.query();\n\t\t\tif ( queryName.isBlank() ) {\n\t\t\t\tthrow new AnnotationException(\n\t\t\t\t\t\t\"Class or package level '@NamedQuery' annotation must specify a 'name'\" );\n\t\t\t}\n\n\t\t\tif ( BOOT_LOGGER.isTraceEnabled() ) {\n\t\t\t\tBOOT_LOGGER.bindingNamedQuery( queryName,\n\t\t\t\t\t\tqueryString.replace( '\\n', ' ' ) );\n\t\t\t}\n\n\t\t\tfinal var definition = NamedHqlSelectionDefinitionImpl.from( namedQuery, annotationTarget );\n\t\t\tfinal var collector = context.getMetadataCollector();\n\t\t\tif ( isDefault ) {\n\t\t\t\tcollector.addDefaultQuery( definition );\n\t\t\t}\n\t\t\telse {\n\t\t\t\tcollector.addNamedQuery( definition );\n\t\t\t}\n\t\t}\n\t}","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryBinder.java#L81-L117","documentation":"QueryBinder.bindQuery registers a jakarta.persistence @NamedQuery; if its name() is blank the AnnotationException is thrown at bootstrap. Every named query must be registered under a non-empty unique key, and blank (empty or whitespace-only) names cannot be looked up later.","triggerScenarios":"@NamedQuery(name = \"\", query = \"...\") or a name built from an empty constant, declared at class or package level and processed during metadata building. Also triggered by code generators that emit the annotation without filling name.","commonSituations":"Copy-pasting a @NamedQuery and forgetting to change the name field; annotation processors/templates emitting empty names; name supplied via a constant that was never set; trimming whitespace-only names during refactors.","solutions":["Give the query a unique non-blank name, conventionally EntityName.methodName (e.g. \"Person.findByEmail\").","If names come from constants, populate and unit-test the constants (assert !name.isBlank()).","Audit generated mapping sources (XML, generated classes) for empty name attributes when the error appears after a build."],"exampleFix":"// before\n@NamedQuery(name = \"\", query = \"select p from Person p where p.email = :email\")\n\n// after\n@NamedQuery(name = \"Person.findByEmail\", query = \"select p from Person p where p.email = :email\")","handlingStrategy":"validation","validationCode":"// names live in constants; test them before the mapping ships\npublic static final String PERSON_BY_EMAIL = \"Person.findByEmail\";\n\n@Test void queryNamesNotBlank() {\n    assertTrue(!Queries.PERSON_BY_EMAIL.isBlank());\n}","typeGuard":null,"tryCatchPattern":"try {\n    metadata = sources.buildMetadata();\n} catch (AnnotationException e) {\n    failBuild(\"Named query registration failed: \" + e.getMessage());\n}","preventionTips":["Name queries EntityName.methodName by convention.","Source names from one constants class so a single test guards them.","Review generated mapping code for empty name attributes after builds."],"tags":["hibernate","orm","named-query","annotation","boot"],"backgroundTag":"named-query-missing-name","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}