{"record":{"id":"e0ea83cc3136cad7","repo":"hibernate/hibernate-orm","slug":"no-filter-named-filtername","errorCode":null,"errorMessage":"No filter named '{filterName}'","messagePattern":"No filter named '(.+?)'","errorType":"exception","errorClass":"UnknownFilterException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java","lineNumber":1331,"sourceCode":"\t}\n\n\tprivate transient StatisticsImplementor statistics;\n\n\t@Override\n\t@Nonnull\n\tpublic StatisticsImplementor getStatistics() {\n\t\tif ( statistics == null ) {\n\t\t\tstatistics = serviceRegistry.requireService( StatisticsImplementor.class );\n\t\t}\n\t\treturn statistics;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic FilterDefinition getFilterDefinition(@Nonnull String filterName) {\n\t\tfinal var filterDefinition = filters.get( filterName );\n\t\tif ( filterDefinition == null ) {\n\t\t\tthrow new UnknownFilterException( filterName );\n\t\t}\n\t\treturn filterDefinition;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic Collection<FilterDefinition> getAutoEnabledFilters() {\n\t\treturn autoEnabledFilters;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic Set<String> getDefinedFilterNames() {\n\t\treturn unmodifiableSet( filters.keySet() );\n\t}\n\n\t@Override\n\tpublic boolean containsFetchProfileDefinition(@Nonnull String name) {","sourceCodeStart":1313,"sourceCodeEnd":1349,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java#L1313-L1349","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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=...)","Fix the name string to exactly match the @FilterDef name (case-sensitive)","Verify the class/package holding @FilterDef is part of the persistence unit (listed in persistence.xml, scanned by Spring, or added via Configuration.addClass)","At startup, log sessionFactory.getDefinedFilterNames() once to see what is actually registered"],"exampleFix":"// before\nsession.enableFilter(\"region\"); // no @FilterDef(\"region\") anywhere -> UnknownFilterException\n\n// after\n@Entity\n@FilterDef(name = \"region\", parameters = @ParamDef(name = \"code\", type = String.class))\n@Filter(name = \"region\", condition = \"region_code = :code\")\npublic class Customer { ... }\n\n// ...\nvar filter = session.enableFilter(\"region\");\nfilter.setParameter(\"code\", \"EMEA\");","handlingStrategy":"validation","validationCode":"Set<String> defined = sessionFactory.getDefinedFilterNames();\nif (!defined.contains(filterName)) {\n    throw new IllegalArgumentException(\n        \"Unknown filter '\" + filterName + \"'. Defined: \" + defined);\n}\nsession.enableFilter(filterName);","typeGuard":null,"tryCatchPattern":"try {\n    return sessionFactory.getFilterDefinition(filterName);\n} catch (UnknownFilterException e) {\n    // filter-def missing from metadata: report configured names to speed up the fix\n    throw new IllegalArgumentException(\n        \"No @FilterDef for '\" + filterName + \"'; defined: \"\n            + sessionFactory.getDefinedFilterNames(), e);\n}","preventionTips":["Centralize @FilterDef declarations (package-info or a base entity) so they are hard to lose in refactors","Log sessionFactory.getDefinedFilterNames() at startup and compare against the filter names your code enables","Use constants for filter names instead of string literals scattered across repositories"],"tags":["hibernate","filters","filter-def","metadata","metamodel"],"backgroundTag":"unknown-named-object","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}