hibernate/hibernate-orm · error · IllegalArgumentException

The specified package name cannot be null

Error message

The specified package name cannot be null

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java:300

	public MetadataSources addQueryImport(String importedName, Class<?> target) {
		if ( extraQueryImports == null ) {
			extraQueryImports = new HashMap<>();
		}
		extraQueryImports.put( importedName, target );
		return this;
	}

	/**
	 * Read package-level metadata.
	 *
	 * @param packageName java package name without trailing '.', cannot be {@code null}
	 *
	 * @return this (for method chaining)
	 */
	public MetadataSources addPackage(String packageName) {
		if ( packageName == null ) {
			throw new IllegalArgumentException( "The specified package name cannot be null" );
		}

		if ( packageName.endsWith( "." ) ) {
			packageName = packageName.substring( 0, packageName.length() - 1 );
		}

		addPackageInternal( packageName );
		return this;
	}

	private void addPackageInternal(String packageName) {
		if ( annotatedPackages == null ) {
			annotatedPackages = new LinkedHashSet<>();
		}
		annotatedPackages.add( packageName );
	}

	/**

View on GitHub (pinned to fad1729dce)

Solutions

1. Pass a non-null fully-qualified package name, e.g. sources.addPackage("com.acme.model").
2. Validate or default the value before calling: Objects.requireNonNullElse(pkg, "com.acme.model").
3. Check the configuration source (property file, env var) for the missing entry.

Example fix

// before
String pkg = System.getProperty("entities.pkg");
sources.addPackage(pkg); // NPE-path: throws IllegalArgumentException

// after
String pkg = Objects.requireNonNull(
        System.getProperty("entities.pkg"), "entities.pkg must be set");
sources.addPackage(pkg);

String pkg = config.get("entities.package");
if (pkg == null || pkg.isBlank()) {
    throw new IllegalArgumentException("entities.package must be configured");
}
sources.addPackage(pkg);

Optionally catch IllegalArgumentException around addPackage and rethrow with the config key that supplied the null value.

When it happens

Trigger: Calling sources.addPackage(null) — typically the value comes from a system property, environment variable, or configuration entry that was never set.

Common situations: Package names read from build/runtime config that is missing in a new environment; refactoring that removed the constant; conditional configuration skipping the assignment.

Related errors

• Named query definition is null
• Named native query definition object is null
• Result-set mapping was null
• Import name or entity name is null
• Column with logical name '%s' in table '%s' cannot be mapped

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/a12c5f6502331105. Report an issue: GitHub.