{"record":{"id":"600098e00a8302f8","repo":"hibernate/hibernate-orm","slug":"named-native-query-definition-name-is-null","errorCode":null,"errorMessage":"Named native query definition name is null: {}","messagePattern":"Named native query definition name is null: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java","lineNumber":758,"sourceCode":"\t// Named native-query handling\n\n\t@Override\n\tpublic NamedNativeQueryDefinition<?> getNamedNativeQueryMapping(String name) {\n\t\treturn namedNativeQueryMap.get( name );\n\t}\n\n\t@Override\n\tpublic void visitNamedNativeQueryDefinitions(Consumer<NamedNativeQueryDefinition<?>> definitionConsumer) {\n\t\tnamedNativeQueryMap.values().forEach( definitionConsumer );\n\t}\n\n\t@Override\n\tpublic void addNamedNativeQuery(NamedNativeQueryDefinition<?> def) {\n\t\tif ( def == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Named native query definition object is null\" );\n\t\t}\n\t\telse if ( def.getRegistrationName() == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Named native query definition name is null: \" + def.getSqlQueryString() );\n\t\t}\n\t\telse if ( !defaultNamedNativeQueryNames.contains( def.getRegistrationName() ) ) {\n\t\t\tapplyNamedNativeQuery( def.getRegistrationName(), def );\n\t\t}\n\t}\n\n\tprivate void applyNamedNativeQuery(String name, NamedNativeQueryDefinition<?> query) {\n\t\tcheckQueryName( name );\n\t\tnamedNativeQueryMap.put( name.intern(), query );\n\t}\n\n\t@Override\n\tpublic void addDefaultNamedNativeQuery(NamedNativeQueryDefinition<?> query) {\n\t\tapplyNamedNativeQuery( query.getRegistrationName(), query );\n\t\tdefaultNamedNativeQueryNames.add( query.getRegistrationName() );\n\t}\n\n","sourceCodeStart":740,"sourceCodeEnd":776,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L740-L776","documentation":"A native query definition arrived with a null registration name. The exception text embeds the raw SQL of the offending query so the broken declaration can be found by search. Without a name the query can never be looked up, so the collector rejects it and bootstrap stops.","triggerScenarios":"An orm.xml <named-native-query> (or hbm.xml <sql-query>) element missing its name attribute; a NamedNativeQueryDefinitionBuilder used without setName(...); contributor code copying definitions and losing the name.","commonSituations":"Hand-edited XML mappings that no longer validate, migration tooling dropping attributes, and programmatically generated native queries whose names come from empty config values.","solutions":["Copy the SQL from the message into a project search to find the declaration","XML: add the required name attribute to the <named-native-query>/<sql-query> element","Builder: call setName(...) before build()","Validate orm.xml against the persistence schema in CI so missing attributes are caught statically"],"exampleFix":"<!-- before -->\n<named-native-query>\n    <query>SELECT * FROM users WHERE active = 1</query>\n</named-native-query>\n\n<!-- after -->\n<named-native-query name=\"User.findActiveNative\">\n    <query>SELECT * FROM users WHERE active = 1</query>\n</named-native-query>","handlingStrategy":"validation","validationCode":"if ( def == null || def.getRegistrationName() == null || def.getRegistrationName().isBlank() ) {\n    throw new IllegalStateException( \"Native query missing registration name; sql=\" + def );\n}\ncollector.addNamedNativeQuery( def );","typeGuard":"static boolean hasRegistrationName( NamedNativeQueryDefinition<?> def ) {\n    return def != null && def.getRegistrationName() != null && !def.getRegistrationName().isBlank();\n}","tryCatchPattern":"try {\n    metadata.buildSessionFactory();\n} catch ( IllegalArgumentException e ) {\n    if ( e.getMessage() != null && e.getMessage().startsWith( \"Named native query definition name is null\" ) ) {\n        // message contains the raw SQL — search the project for it\n        throw new IllegalStateException( \"Nameless native query: \" + e.getMessage(), e );\n    }\n    throw e;\n}","preventionTips":["Validate orm.xml against the persistence XSD so missing name attributes fail early","Require the name in builder wrappers","Pair query names and SQL in one place to avoid drift"],"tags":["hibernate","orm","java","bootstrap","native-query","orm-xml"],"backgroundTag":"missing-mapping-name","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}