{"record":{"id":"a12c5f6502331105","repo":"hibernate/hibernate-orm","slug":"the-specified-package-name-cannot-be-null","errorCode":null,"errorMessage":"The specified package name cannot be null","messagePattern":"The specified package name cannot be null","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java","lineNumber":300,"sourceCode":"\n\tpublic MetadataSources addQueryImport(String importedName, Class<?> target) {\n\t\tif ( extraQueryImports == null ) {\n\t\t\textraQueryImports = new HashMap<>();\n\t\t}\n\t\textraQueryImports.put( importedName, target );\n\t\treturn this;\n\t}\n\n\t/**\n\t * Read package-level metadata.\n\t *\n\t * @param packageName java package name without trailing '.', cannot be {@code null}\n\t *\n\t * @return this (for method chaining)\n\t */\n\tpublic MetadataSources addPackage(String packageName) {\n\t\tif ( packageName == null ) {\n\t\t\tthrow new IllegalArgumentException( \"The specified package name cannot be null\" );\n\t\t}\n\n\t\tif ( packageName.endsWith( \".\" ) ) {\n\t\t\tpackageName = packageName.substring( 0, packageName.length() - 1 );\n\t\t}\n\n\t\taddPackageInternal( packageName );\n\t\treturn this;\n\t}\n\n\tprivate void addPackageInternal(String packageName) {\n\t\tif ( annotatedPackages == null ) {\n\t\t\tannotatedPackages = new LinkedHashSet<>();\n\t\t}\n\t\tannotatedPackages.add( packageName );\n\t}\n\n\t/**","sourceCodeStart":282,"sourceCodeEnd":318,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java#L282-L318","documentation":"MetadataSources.addPackage(String) requires a non-null package name and fails fast with IllegalArgumentException on null. Trailing dots are trimmed automatically; only null (not blank) is checked at this point.","triggerScenarios":"Calling sources.addPackage(null) — typically the value comes from a system property, environment variable, or configuration entry that was never set.","commonSituations":"Package names read from build/runtime config that is missing in a new environment; refactoring that removed the constant; conditional configuration skipping the assignment.","solutions":["Pass a non-null fully-qualified package name, e.g. sources.addPackage(\"com.acme.model\").","Validate or default the value before calling: Objects.requireNonNullElse(pkg, \"com.acme.model\").","Check the configuration source (property file, env var) for the missing entry."],"exampleFix":"// before\nString pkg = System.getProperty(\"entities.pkg\");\nsources.addPackage(pkg); // NPE-path: throws IllegalArgumentException\n\n// after\nString pkg = Objects.requireNonNull(\n        System.getProperty(\"entities.pkg\"), \"entities.pkg must be set\");\nsources.addPackage(pkg);","handlingStrategy":"validation","validationCode":"String pkg = config.get(\"entities.package\");\nif (pkg == null || pkg.isBlank()) {\n    throw new IllegalArgumentException(\"entities.package must be configured\");\n}\nsources.addPackage(pkg);","typeGuard":null,"tryCatchPattern":"Optionally catch IllegalArgumentException around addPackage and rethrow with the config key that supplied the null value.","preventionTips":["Never pass config-derived strings unchecked into addPackage.","Fail fast on missing configuration at startup with a clear message naming the key."],"tags":["hibernate","null-check","illegalargument","bootstrap"],"backgroundTag":"illegal-argument-null","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}