{"record":{"id":"5c4b234d047a16a5","repo":"hibernate/hibernate-orm","slug":"named-query-definition-is-null","errorCode":null,"errorMessage":"Named query definition is null","messagePattern":"Named query definition is null","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java","lineNumber":712,"sourceCode":"\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Named query handling\n\n\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}","sourceCodeStart":694,"sourceCodeEnd":730,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L694-L730","documentation":"Hibernate registers every named HQL query (from @NamedQuery, orm.xml/hbm.xml <query>, or programmatic contributions) in the in-flight metadata collector during SessionFactory bootstrap. This exception means addNamedQuery(...) received a null NamedHqlQueryDefinition, i.e. some mapping contributor produced no definition object at all. The collector never stores null definitions, so bootstrap aborts immediately.","triggerScenarios":"Calling InFlightMetadataCollector.addNamedQuery(null) from custom code, or a custom org.hibernate.boot.spi.MetadataContributor forwarding the result of a builder (e.g. NamedHqlQueryDefinitionBuilder) that returned null because it was incompletely configured.","commonSituations":"Hand-written MetadataContributor extensions, programmatic bootstrap that builds query definitions from config files where a missing entry yields null, and Hibernate major upgrades where contributor/builder APIs changed and stale implementations now pass null.","solutions":["Null-check the definition right before registering it and throw a clear error naming the contributor that produced it","Trace the null to its source: usually a NamedHqlQueryDefinitionBuilder invoked without setHqlString/setName — complete the builder call chain","If you have no custom contributor, bisect third-party jars that register META-INF/services/org.hibernate.boot.spi.MetadataContributor and upgrade or remove the stale one","Re-run bootstrap after each change; this guard always fails the whole SessionFactory build"],"exampleFix":"// before\ncollector.addNamedQuery( buildNamedQuery( props ) );\n\n// after\nfinal NamedHqlQueryDefinition<?> def = buildNamedQuery( props );\nif ( def == null ) {\n    throw new IllegalStateException( \"Query contributor returned no definition for: \" + props );\n}\ncollector.addNamedQuery( def );","handlingStrategy":"validation","validationCode":"NamedHqlQueryDefinition<?> def = buildNamedQuery( source );\nif ( def == null || def.getRegistrationName() == null ) {\n    throw new IllegalStateException( \"Invalid named-query definition produced from: \" + source );\n}\ncollector.addNamedQuery( def );","typeGuard":"static boolean isRegistrableQuery( NamedHqlQueryDefinition<?> def ) {\n    return def != null\n            && def.getRegistrationName() != null\n            && def.getHqlString() != null;\n}","tryCatchPattern":"try {\n    sessionFactory = metadata.buildSessionFactory();\n} catch ( IllegalArgumentException e ) {\n    if ( e.getMessage() != null && e.getMessage().contains( \"Named query definition\" ) ) {\n        // a mapping contributor passed a null definition — fix the producer, not the caller\n        throw new IllegalStateException( \"Broken named-query contributor: \" + e.getMessage(), e );\n    }\n    throw e;\n}","preventionTips":["Never forward builder results to the collector without a null check","Fail inside the contributor with a descriptive message instead of letting Hibernate's generic guard fire","Boot the SessionFactory in a CI test so broken contributors are caught at build time"],"tags":["hibernate","orm","java","bootstrap","named-query","null-check"],"backgroundTag":"null-argument-validation","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}