{"record":{"id":"cf3745f2f4a81e71","repo":"hibernate/hibernate-orm","slug":"class-or-package-level-namedstatement-annotatio","errorCode":null,"errorMessage":"Class or package level '@NamedStatement' annotation must specify a 'name'","messagePattern":"Class or package level '@NamedStatement' 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":126,"sourceCode":"\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}\n\n\tpublic static void bindStatement(\n\t\t\tNamedStatement annotation,\n\t\t\tMetadataBuildingContext context,\n\t\t\tAnnotationTarget location) {\n\t\tif ( annotation != null ) {\n\t\t\tfinal String registrationName = annotation.name();\n\t\t\tif ( registrationName.isBlank() ) {\n\t\t\t\tthrow new AnnotationException(\n\t\t\t\t\t\t\"Class or package level '@NamedStatement' annotation must specify a 'name'\" );\n\t\t\t}\n\n\t\t\tif ( BOOT_LOGGER.isTraceEnabled() ) {\n\t\t\t\tBOOT_LOGGER.bindingNamedMutation( registrationName,\n\t\t\t\t\t\tannotation.statement().replace( '\\n', ' ' ) );\n\t\t\t}\n\n\t\t\tfinal var definition = NamedHqlMutationDefinitionImpl.from( annotation, location );\n\t\t\tcontext.getMetadataCollector().addNamedQuery( definition );\n\t\t}\n\t}\n\n\tpublic static void bindNativeStatement(\n\t\t\tNamedNativeStatement annotation,\n\t\t\tMetadataBuildingContext context,\n\t\t\tAnnotationTarget location) {\n\t\tif ( annotation != null ) {","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryBinder.java#L108-L144","documentation":"QueryBinder.bindStatement registers a Hibernate-specific @NamedStatement (an HQL INSERT/UPDATE/DELETE 'mutation' statement); if annotation.name() is blank, bootstrap throws AnnotationException. Like named queries, named statements need a non-empty registration key.","triggerScenarios":"@NamedStatement(name = \"\", statement = \"update Person p set p.active = true\") declared on an entity or package and processed during annotation binding. Blank means empty or whitespace-only.","commonSituations":"Adopting Hibernate 6.2+ @NamedStatement and copying @NamedQuery examples with the wrong member names; leaving name empty while iterating on the statement text; generated or externalized statement catalogs missing the key.","solutions":["Set a unique non-blank name on the @NamedStatement annotation.","Keep statement names in constants and test they are non-blank before release.","If names are generated, fix the generator to always emit a key."],"exampleFix":"// before\n@NamedStatement(name = \"\", statement = \"update Person p set p.active = true\")\n\n// after\n@NamedStatement(name = \"Person.activateAll\", statement = \"update Person p set p.active = true\")","handlingStrategy":"validation","validationCode":"@Test void namedStatementsHaveNames() {\n    NamedStatement s = Order.class.getAnnotation(NamedStatement.class);\n    if (s != null) assertTrue(!s.name().isBlank(), \"@NamedStatement needs a name\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    metadata = sources.buildMetadata();\n} catch (AnnotationException e) {\n    failBuild(\"Named statement registration failed: \" + e.getMessage());\n}","preventionTips":["Treat @NamedStatement like named queries: constant-backed unique names.","Add a reflection scan over annotated classes asserting non-blank names in CI."],"tags":["hibernate","orm","named-statement","hql-dml","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"}