{"record":{"id":"cbac852607f5149c","repo":"hibernate/hibernate-orm","slug":"import-name-or-entity-name-is-null","errorCode":null,"errorMessage":"Import name or entity name is null","messagePattern":"Import name or entity name is null","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java","lineNumber":878,"sourceCode":"\t\t\tsqlResultSetMappingMap.remove( name );\n\t\t}\n\t\tapplyResultSetMapping( definition );\n\t\tdefaultSqlResultSetMappingNames.add( name );\n\t}\n\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// imports\n\n\t@Override\n\tpublic Map<String,String> getImports() {\n\t\treturn imports;\n\t}\n\n\t@Override\n\tpublic void addImport(String importName, String className) {\n\t\tif ( importName == null || className == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Import name or entity name is null\" );\n\t\t}\n\t\tBOOT_LOGGER.importEntry( importName, className );\n\t\tfinal String old = imports.put( importName, className);\n\t\tif ( old != null ) {\n\t\t\tBOOT_LOGGER.importOverrodePrevious( importName, old );\n\t\t}\n\t}\n\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Table handling\n\n\t@Override\n\tpublic Table addTable(\n\t\t\tString schemaName,\n\t\t\tString catalogName,\n\t\t\tString name,\n\t\t\tString subselectFragment,","sourceCodeStart":860,"sourceCodeEnd":896,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L860-L896","documentation":"addImport(...) registers the mapping from an unqualified HQL entity name (or an explicit hbm.xml <import rename=\"...\">) to the entity name. This IllegalArgumentException means importName or className was null — the import table cannot hold partial entries. Almost always raised from programmatic/contributor code, not plain annotation applications.","triggerScenarios":"Calling metadataCollector.addImport(name, null) or addImport(null, cls) from custom code; dynamic-map entities whose entity-name resolution returned null; broken <import> handling in custom binders.","commonSituations":"Custom MetadataContributors adding HQL short names, tooling that mirrors hbm.xml <import> elements, and upgrades that changed dynamic-map name handling.","solutions":["Guard both arguments with null checks before calling addImport","Log the (importName, className) pair at registration so the broken entry is identifiable","If the values come from config, validate them at load time and report the offending key"],"exampleFix":"// before\ncollector.addImport( entry.get( \"rename\" ), entry.get( \"class\" ) );\n\n// after\nfinal String rename = entry.get( \"rename\" );\nfinal String className = entry.get( \"class\" );\nif ( rename == null || className == null ) {\n    throw new IllegalStateException( \"Incomplete <import> entry: \" + entry );\n}\ncollector.addImport( rename, className );","handlingStrategy":"validation","validationCode":"if ( importName == null || className == null ) {\n    throw new IllegalStateException( \"Incomplete import entry: rename=\" + importName + \", class=\" + className );\n}\ncollector.addImport( importName, className );","typeGuard":"static boolean isCompleteImport( String importName, String className ) {\n    return importName != null && !importName.isBlank()\n            && className != null && !className.isBlank();\n}","tryCatchPattern":"try {\n    metadata.buildSessionFactory();\n} catch ( IllegalArgumentException e ) {\n    if ( e.getMessage() != null && e.getMessage().contains( \"Import name or entity name is null\" ) ) {\n        throw new IllegalStateException( \"Incomplete entity import registered by a contributor\", e );\n    }\n    throw e;\n}","preventionTips":["Validate import entries at configuration load time","Log (importName, className) pairs when registering imports","Prefer @Entity(name=...) over hbm.xml <import> where possible"],"tags":["hibernate","orm","java","bootstrap","entity-imports","null-check"],"backgroundTag":"null-argument-validation","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}