hibernate/hibernate-orm · error · IllegalArgumentException

Filter definition object or name is null: %s

Error message

Filter definition object or name is null: %s

What it means

InFlightMetadataCollectorImpl.addFilterDefinition requires a FilterDefinition object with a non-null filter name. Passing null - either the definition itself or its getFilterName() - throws IllegalArgumentException 'Filter definition object or name is null' with the (possibly null) definition appended. This guard runs before the map insert, so nothing is partially registered.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java:589

	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// filter definitions

	@Override
	public Map<String, FilterDefinition> getFilterDefinitions() {
		return filterDefinitionMap;
	}

	@Override
	public FilterDefinition getFilterDefinition(String name) {
		return filterDefinitionMap.get( name );
	}

	@Override
	public void addFilterDefinition(FilterDefinition filterDefinition) {
		if ( filterDefinition == null || filterDefinition.getFilterName() == null ) {
			throw new IllegalArgumentException( "Filter definition object or name is null: "  + filterDefinition );
		}
		filterDefinitionMap.put( filterDefinition.getFilterName(), filterDefinition );
	}


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// fetch profiles

	@Override
	public java.util.Collection<FetchProfile> getFetchProfiles() {
		return fetchProfileMap.values();
	}

	@Override
	public FetchProfile getFetchProfile(String name) {
		return fetchProfileMap.get( name );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Construct the FilterDefinition with a non-null name before registering it
2. Null-check the definition and its name at the registration boundary and fail with a descriptive error
3. Fix the source configuration/XML so every filter definition declares a name

Example fix

// before
collector.addFilterDefinition(filterDef); // filterDef or its name is null

// after
if (filterDef == null || filterDef.getFilterName() == null) {
    throw new IllegalArgumentException("filter definition requires a name");
}
collector.addFilterDefinition(filterDef);

Objects.requireNonNull(filterDefinition, "filter definition");
Objects.requireNonNull(filterDefinition.getFilterName(), "filter name");
collector.addFilterDefinition(filterDefinition);

static boolean isRegistrableFilter(FilterDefinition d) {
    return d != null && d.getFilterName() != null;
}

When it happens

Trigger: Programmatic metadata or integration code calling addFilterDefinition(null), or with a FilterDefinition constructed without a name; XML <filter-def> elements with a missing name attribute surface here as well once parsed.

Common situations: Custom integrations registering filters built from configuration maps where the name key is absent; dynamic filter registration driven by user input; generated mappings with incomplete filter definitions.

Related errors

• Fetch profile object or name is null: %s
• null is not a valid generator name
• Id generator object or name is null
• null is not a valid query name
• The specified package name cannot be null

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