{"record":{"id":"7c2e78604ddf2672","repo":"hibernate/hibernate-orm","slug":"named-native-query-definition-object-is-null","errorCode":null,"errorMessage":"Named native query definition object is null","messagePattern":"Named native query definition object is null","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java","lineNumber":755,"sourceCode":"\t}\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\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() );","sourceCodeStart":737,"sourceCodeEnd":773,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L737-L773","documentation":"Same guard as for HQL queries but on the native side: addNamedNativeQuery(...) was called with a null NamedNativeQueryDefinition during metadata collection. The definition is the only carrier of the SQL string, result-set mapping and hints, so nothing can be registered from null. Bootstrap fails immediately.","triggerScenarios":"A custom MetadataContributor or programmatic bootstrap path calling addNamedNativeQuery(null); a NamedNativeQueryDefinitionBuilder whose build() result was forwarded without a null check after missing configuration.","commonSituations":"Libraries that register native queries from config files or JSON descriptors, contributor code written against older Hibernate versions, and half-initialized builders after refactors.","solutions":["Null-check the definition right before registration and fail with a message naming the producer","Fix the builder: an incompletely configured NamedNativeQueryDefinitionBuilder is the usual source of null","Audit META-INF/services contributor registrations after upgrading Hibernate"],"exampleFix":"// before\ncollector.addNamedNativeQuery( buildNativeQuery( descriptor ) );\n\n// after\nfinal NamedNativeQueryDefinition<?> def = buildNativeQuery( descriptor );\nif ( def == null ) {\n    throw new IllegalStateException( \"No native-query definition built for \" + descriptor );\n}\ncollector.addNamedNativeQuery( def );","handlingStrategy":"validation","validationCode":"NamedNativeQueryDefinition<?> def = buildNativeQuery( source );\nif ( def == null || def.getRegistrationName() == null ) {\n    throw new IllegalStateException( \"Invalid native-query definition from: \" + source );\n}\ncollector.addNamedNativeQuery( def );","typeGuard":"static boolean isRegistrableNativeQuery( NamedNativeQueryDefinition<?> def ) {\n    return def != null\n            && def.getRegistrationName() != null\n            && def.getSqlQueryString() != null;\n}","tryCatchPattern":"try {\n    metadata.buildSessionFactory();\n} catch ( IllegalArgumentException e ) {\n    if ( e.getMessage() != null && e.getMessage().contains( \"native query definition object is null\" ) ) {\n        throw new IllegalStateException( \"Broken native-query contributor: \" + e.getMessage(), e );\n    }\n    throw e;\n}","preventionTips":["Null-check builder output before every addNamedNativeQuery call","Make incomplete configuration fail loudly in the producer","Cover contributor code with a bootstrap integration test"],"tags":["hibernate","orm","java","bootstrap","native-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"}