{"record":{"id":"7789853b175c19f8","repo":"hibernate/hibernate-orm","slug":"named-query-definition-name-is-null-s","errorCode":null,"errorMessage":"Named query definition name is null: %s","messagePattern":"Named 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":715,"sourceCode":"\tpublic NamedHqlQueryDefinition<?> getNamedHqlQueryMapping(String name) {\n\t\tif ( name == null ) {\n\t\t\tthrow new IllegalArgumentException( \"null is not a valid query name\" );\n\t\t}\n\t\treturn namedQueryMap.get( name );\n\t}\n\n\t@Override\n\tpublic void visitNamedHqlQueryDefinitions(Consumer<NamedHqlQueryDefinition<?>> definitionConsumer) {\n\t\tnamedQueryMap.values().forEach( definitionConsumer );\n\t}\n\n\t@Override\n\tpublic void addNamedQuery(NamedHqlQueryDefinition<?> def) {\n\t\tif ( def == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Named query definition is null\" );\n\t\t}\n\t\telse if ( def.getRegistrationName() == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Named query definition name is null: \" + def.getHqlString() );\n\t\t}\n\t\telse if ( !defaultNamedQueryNames.contains( def.getRegistrationName() ) ) {\n\t\t\tapplyNamedQuery( def.getRegistrationName(), def );\n\t\t}\n\t}\n\n\tprivate void applyNamedQuery(String name, NamedHqlQueryDefinition<?> query) {\n\t\tcheckQueryName( name );\n\t\tnamedQueryMap.put( name.intern(), query );\n\t}\n\n\tprivate void checkQueryName(String name) throws DuplicateMappingException {\n\t\tif ( namedQueryMap.containsKey( name ) || namedNativeQueryMap.containsKey( name ) ) {\n\t\t\tthrow new DuplicateMappingException( DuplicateMappingException.Type.QUERY, name );\n\t\t}\n\t}\n\n\t@Override","sourceCodeStart":697,"sourceCodeEnd":733,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L697-L733","documentation":"A named query definition reached the collector with a null registration name — the key under which session.createNamedQuery(name) later resolves it. The message appends the raw HQL string precisely so the broken declaration can be found by search. Hibernate cannot register a query without a lookup key, so bootstrap fails.","triggerScenarios":"A NamedHqlQueryDefinitionBuilder used without setName(...); an orm.xml <query> element missing the required name attribute; a custom contributor that copies definitions and drops the name field.","commonSituations":"Hand-edited orm.xml files that no longer pass schema validation, Jakarta-migration tooling rewriting mapping files and dropping attributes, and programmatic bootstrap where the name comes from config and is silently empty.","solutions":["Copy the HQL shown in the message into a project-wide search to locate the declaration","orm.xml: add the name attribute to the <query> element","Builder-based registration: call setName(...) before passing the definition to the collector","Guard programmatic definitions with Objects.requireNonNull(def.getRegistrationName()) at build time"],"exampleFix":"// before — no name set\ncollector.addNamedQuery( new NamedHqlQueryDefinitionBuilder()\n        .setHqlString( \"from User u where u.active = true\" )\n        .build() );\n\n// after\ncollector.addNamedQuery( new NamedHqlQueryDefinitionBuilder()\n        .setName( \"User.findActive\" )\n        .setHqlString( \"from User u where u.active = true\" )\n        .build() );","handlingStrategy":"validation","validationCode":"if ( def == null || def.getRegistrationName() == null || def.getRegistrationName().isBlank() ) {\n    throw new IllegalStateException( \"Named query missing registration name; hql=\" + def );\n}\ncollector.addNamedQuery( def );","typeGuard":"static boolean hasRegistrationName( NamedHqlQueryDefinition<?> 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 query definition name is null\" ) ) {\n        // message contains the HQL — use it to find the broken declaration\n        throw new IllegalStateException( \"Nameless named query: \" + e.getMessage(), e );\n    }\n    throw e;\n}","preventionTips":["Validate orm.xml against the persistence XSD in CI — a missing name attribute fails schema validation","Wrap builders so a name is required: Objects.requireNonNull(name)","Centralize query-name constants instead of scattering string literals"],"tags":["hibernate","orm","java","bootstrap","named-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"}