hibernate/hibernate-orm · error · NullPointerException

prefix or name were null attempting to build qualified name

Error message

prefix or name were null attempting to build qualified name

What it means

StringHelper.qualify(prefix, name) builds 'prefix.name' for qualified identifiers (schema.table, entity.property) and is null-hostile in both arguments. Either null triggers an immediate NullPointerException with this message. Inside Hibernate, a null reaching qualify usually means upstream metadata — a schema, table, column, or property name — resolved to null unexpectedly.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/internal/util/StringHelper.java:582

	public static boolean isNotEmpty(@Nullable String string) {
		return string != null && !string.isEmpty();
	}

	public static boolean isEmpty(@Nullable String string) {
		return string == null || string.isEmpty();
	}

	public static boolean isNotBlank(@Nullable String string) {
		return string != null && !string.isBlank();
	}

	public static boolean isBlank(@Nullable String string) {
		return string == null || string.isBlank();
	}

	public static String qualify(String prefix, String name) {
		if ( name == null || prefix == null ) {
			throw new NullPointerException( "prefix or name were null attempting to build qualified name" );
		}
		return prefix + '.' + name;
	}

	public static String qualifyConditionally(String prefix, String name) {
		if ( name == null ) {
			throw new NullPointerException( "name was null attempting to build qualified name" );
		}
		return isEmpty( prefix ) ? name : prefix + '.' + name;
	}

	/**
	 * Qualifies {@code name} with {@code prefix} separated by a '.' if<ul>
	 *     <li>{@code name} is not already qualified</li>
	 *     <li>{@code prefix} is not null</li>
	 * </ul>
	 *
	 * @apiNote Similar to {@link #qualifyConditionally}, except that here we explicitly

View on GitHub (pinned to fad1729dce)

Solutions

1. Null-check both arguments at your boundary and fail with a contextual error.
2. Fix the upstream producer (naming strategy, mapping builder) so name components are never null.
3. If an empty prefix is legitimate at your call site, use qualifyConditionally(prefix, name) which tolerates empty prefixes.

Example fix

// before
String qualified = StringHelper.qualify(schema, tableName); // schema == null -> NPE

// after
String qualified = StringHelper.isEmpty(schema) ? tableName : StringHelper.qualify(schema, tableName);
// or: StringHelper.qualifyConditionally(schema, tableName);

static String qualifySafe(String prefix, String name) {
    if (name == null) throw new IllegalArgumentException("name must not be null");
    return StringHelper.isEmpty(prefix) ? name : prefix + '.' + name;
}

When it happens

Trigger: Calling qualify(null, name) or qualify(prefix, null) directly, or an internal Hibernate call site where a naming strategy or programmatic mapping produced a null schema/catalog/name component.

Common situations: Custom PhysicalNamingStrategy or ImplicitNamingStrategy implementations returning null; programmatic mapping APIs built with null catalog/schema/entity names; refactors that swap argument order so the nullable value lands in the required slot.

Related errors

• name was null attempting to build qualified name
• The specified package name cannot be null
• Name of class to load cannot be null
• Filter definition object or name is null: %s
• Fetch profile object or name is null: %s

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