{"record":{"id":"dd05dde15bd77949","repo":"hibernate/hibernate-orm","slug":"class-or-package-level-namednativequery-annotat","errorCode":null,"errorMessage":"Class or package level '@NamedNativeQuery' annotation must specify a 'name'","messagePattern":"Class or package level '@NamedNativeQuery' 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":170,"sourceCode":"\t\t\t\tBOOT_LOGGER.bindingNamedNativeMutation( registrationName,\n\t\t\t\t\t\tannotation.statement().replace( '\\n', ' ' ) );\n\t\t\t}\n\n\t\t\tfinal var definition = NamedNativeMutationDefinitionImpl.from( annotation, location );\n\t\t\tcontext.getMetadataCollector().addNamedNativeQuery( definition );\n\t\t}\n\t}\n\n\tpublic static void bindNativeQuery(\n\t\t\tNamedNativeQuery namedNativeQuery,\n\t\t\tMetadataBuildingContext context,\n\t\t\tAnnotationTarget location,\n\t\t\tboolean isDefault) {\n\t\tif ( namedNativeQuery != null ) {\n\t\t\tfinal String registrationName = namedNativeQuery.name();\n\t\t\tfinal String queryString = namedNativeQuery.query();\n\t\t\tif ( registrationName.isBlank() ) {\n\t\t\t\tthrow new AnnotationException(\n\t\t\t\t\t\t\"Class or package level '@NamedNativeQuery' annotation must specify a 'name'\" );\n\t\t\t}\n\n\t\t\tif ( BOOT_LOGGER.isTraceEnabled() ) {\n\t\t\t\tBOOT_LOGGER.bindingNamedNativeQuery( registrationName,\n\t\t\t\t\t\tqueryString.replace( '\\n', ' ' ) );\n\t\t\t}\n\n\t\t\tfinal var collector = context.getMetadataCollector();\n\t\t\tfinal String resultSetMappingName;\n\t\t\tif ( hasInlineResultSetMapping( namedNativeQuery ) ) {\n\t\t\t\tresultSetMappingName = registrationName;\n\t\t\t\tif ( !namedNativeQuery.resultSetMapping().isBlank() ) {\n\t\t\t\t\tthrow new AnnotationException(\n\t\t\t\t\t\t\t\"Named native query '%s' specified both 'resultSetMapping' and an inline result set mapping\"\n\t\t\t\t\t\t\t\t\t.formatted( registrationName )\n\t\t\t\t\t);\n\t\t\t\t}","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryBinder.java#L152-L188","documentation":"QueryBinder.bindNativeQuery registers a jakarta.persistence @NamedNativeQuery; a blank registrationName throws AnnotationException at bootstrap. The name is the key used by entityManager.createNamedQuery(name, ...) and must be non-empty.","triggerScenarios":"@NamedNativeQuery(name = \"\", query = \"SELECT * FROM person\") at class or package level; also a whitespace-only name. Thrown while binding annotations before any query executes.","commonSituations":"Splitting query text across lines and accidentally deleting the name; XML-less migration where name defaulted empty; duplicate annotations where one copy lost its name after merge conflicts.","solutions":["Assign a unique non-blank name to the @NamedNativeQuery.","Verify no merge/refactor left an empty name attribute; grep for name = \"\" across annotations.","Store names in constants covered by a non-blank assertion test."],"exampleFix":"// before\n@NamedNativeQuery(name = \"\", query = \"SELECT * FROM person WHERE email = :email\")\n\n// after\n@NamedNativeQuery(name = \"Person.findByEmailNative\", query = \"SELECT * FROM person WHERE email = :email\")","handlingStrategy":"validation","validationCode":"@Test void nativeQueriesHaveNames() {\n    for (NamedNativeQuery q : Order.class.getAnnotationsByType(NamedNativeQuery.class)) {\n        assertTrue(!q.name().isBlank(), \"@NamedNativeQuery needs a name\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    metadata = sources.buildMetadata();\n} catch (AnnotationException e) {\n    failBuild(\"Named native query registration failed: \" + e.getMessage());\n}","preventionTips":["Use one naming convention for jakarta and Hibernate native query variants.","Grep for name = \"\" after large refactors or merges."],"tags":["hibernate","orm","named-native-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"}