hibernate/hibernate-orm · error · UnknownFilterException

No filter named '{filterName}'

Error message

No filter named '{filterName}'

What it means

SessionFactoryImpl.getFilterDefinition(name) looks up the filter in the map populated from @FilterDef/hbm filter-def metadata at bootstrap. Unknown names produce UnknownFilterException ('No filter named ...'), because filter definitions must exist before sessions can enable them via session.enableFilter(name). The lookup is a plain map get with no fallback.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java:1331

	}

	private transient StatisticsImplementor statistics;

	@Override
	@Nonnull
	public StatisticsImplementor getStatistics() {
		if ( statistics == null ) {
			statistics = serviceRegistry.requireService( StatisticsImplementor.class );
		}
		return statistics;
	}

	@Override
	@Nonnull
	public FilterDefinition getFilterDefinition(@Nonnull String filterName) {
		final var filterDefinition = filters.get( filterName );
		if ( filterDefinition == null ) {
			throw new UnknownFilterException( filterName );
		}
		return filterDefinition;
	}

	@Override
	@Nonnull
	public Collection<FilterDefinition> getAutoEnabledFilters() {
		return autoEnabledFilters;
	}

	@Override
	@Nonnull
	public Set<String> getDefinedFilterNames() {
		return unmodifiableSet( filters.keySet() );
	}

	@Override
	public boolean containsFetchProfileDefinition(@Nonnull String name) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Define the filter: add @FilterDef(name="regionFilter", parameters=...) on the entity or package-info where other defs live, and reference it via @Filter(name="regionFilter", condition=...)
2. Fix the name string to exactly match the @FilterDef name (case-sensitive)
3. Verify the class/package holding @FilterDef is part of the persistence unit (listed in persistence.xml, scanned by Spring, or added via Configuration.addClass)
4. At startup, log sessionFactory.getDefinedFilterNames() once to see what is actually registered

Example fix

// before
session.enableFilter("region"); // no @FilterDef("region") anywhere -> UnknownFilterException

// after
@Entity
@FilterDef(name = "region", parameters = @ParamDef(name = "code", type = String.class))
@Filter(name = "region", condition = "region_code = :code")
public class Customer { ... }

// ...
var filter = session.enableFilter("region");
filter.setParameter("code", "EMEA");

Set<String> defined = sessionFactory.getDefinedFilterNames();
if (!defined.contains(filterName)) {
    throw new IllegalArgumentException(
        "Unknown filter '" + filterName + "'. Defined: " + defined);
}
session.enableFilter(filterName);

try {
    return sessionFactory.getFilterDefinition(filterName);
} catch (UnknownFilterException e) {
    // filter-def missing from metadata: report configured names to speed up the fix
    throw new IllegalArgumentException(
        "No @FilterDef for '" + filterName + "'; defined: "
            + sessionFactory.getDefinedFilterNames(), e);
}

When it happens

Trigger: Calling sessionFactory.getFilterDefinition("regionFilter") when no @FilterDef(name="regionFilter") exists anywhere in the mapped metadata, or when session.enableFilter(name) is called with a misspelled/unimported filter definition. Also when the @FilterDef lives in an entity class excluded from the persistence unit.

Common situations: Copy-pasting filter code between projects without copying the @FilterDef; @FilterDef on a package-info/class that is not scanned (wrong @EntityScan/package-info placement in Spring); renaming a filter definition but missing a call site; using @Filter without a matching @FilterDef.

Related errors

• cannot recreate collection while filter is enabled: " + coll
• cannot recreate collection while filter is enabled [%s : %s]
• #buildNamedQueryRepository should not be called on InFlightM
• You should not be building a SessionFactory from an in-fligh
• Filter definition object or name is null: %s

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