{"record":{"id":"a0a6cc914194afb2","repo":"hibernate/hibernate-orm","slug":"entity-s-with-identifier-value-s-is-filtered-a0a6cc","errorCode":null,"errorMessage":"Entity `%s` with identifier value `%s` is filtered for association `%s`","messagePattern":"Entity `(.+?)` with identifier value `(.+?)` is filtered for association `(.+?)`","errorType":"exception","errorClass":"EntityFilterException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/sql/results/graph/entity/internal/EntitySelectFetchInitializer.java","lineNumber":302,"sourceCode":"\t\tif ( lazyInitializer != null ) {\n\t\t\tlazyInitializer.setUnwrap( unwrapProxy );\n\t\t}\n\t}\n\n\tvoid checkNotFound(EntitySelectFetchInitializerData data) {\n\t\tcheckNotFound( toOneMapping, affectedByFilter,\n\t\t\t\tconcreteDescriptor.getEntityName(),\n\t\t\t\tdata.entityIdentifier );\n\t}\n\n\tstatic void checkNotFound(\n\t\t\tToOneAttributeMapping toOneMapping,\n\t\t\tboolean affectedByFilter,\n\t\t\tString entityName, Object identifier) {\n\t\tfinal var notFoundAction = toOneMapping.getNotFoundAction();\n\t\tif ( notFoundAction != NotFoundAction.IGNORE ) {\n\t\t\tif ( affectedByFilter ) {\n\t\t\t\tthrow new EntityFilterException( entityName, identifier,\n\t\t\t\t\t\ttoOneMapping.getNavigableRole().getFullPath() );\n\t\t\t}\n\t\t\tif ( notFoundAction == NotFoundAction.EXCEPTION ) {\n\t\t\t\tthrow new FetchNotFoundException( entityName, identifier );\n\t\t\t}\n\t\t}\n\t}\n\n\t@Override\n\tpublic void initializeInstanceFromParent(Object parentInstance, Data data) {\n\t\tfinal var attributeMapping = getInitializedPart().asAttributeMapping();\n\t\tfinal Object instance =\n\t\t\t\tattributeMapping != null\n\t\t\t\t\t\t? attributeMapping.getValue( parentInstance )\n\t\t\t\t\t\t: parentInstance;\n\t\tif ( instance == null ) {\n\t\t\tdata.setState( State.MISSING );\n\t\t\tdata.entityIdentifier = null;","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/sql/results/graph/entity/internal/EntitySelectFetchInitializer.java#L284-L320","documentation":"EntitySelectFetchInitializer resolves to-one associations fetched via a secondary SELECT. Its static checkNotFound() helper is invoked after the select: when the target row was not found, notFoundAction != IGNORE, and the association was affected by an enabled filter (@Filter/@SQLRestriction), it throws EntityFilterException('Entity X with identifier value Y is filtered for association <path>'). The row exists but the filter hid it from the follow-up select, which Hibernate reports as the association being 'filtered'.","triggerScenarios":"An association with fetch mode SELECT (e.g. @ManyToOne(fetch=LAZY) resolved later, or proxy initialization selects) where an enabled session filter or @SQLRestriction on the target entity excludes the row with the matching id, combined with a not-ignorable NotFoundAction (default EXCEPTION).","commonSituations":"Soft-delete or tenant filters applied to reference entities that other entities still reference; filters enabled for a specific report but leaking into association loading within the same session; @SQLRestriction(\"active = true\") on entities used as lookup targets.","solutions":["Adjust the filter definition/parameters so referenced rows remain visible (exclude reference tables from soft-delete/tenant filtering).","Annotate the association @NotFound(action = NotFoundAction.IGNORE) or make it optional so a filtered target yields null instead of an exception.","Prefer joined fetch for associations whose targets may be filtered, and handle absence explicitly in business code.","Restore the row so it satisfies the filter condition."],"exampleFix":"// before\n@Entity\n@SQLRestriction(\"archived = false\")\npublic class Product { ... }\n\n@ManyToOne(fetch = FetchType.LAZY) // secondary select hits the restriction\nprivate Product product;\n\n// after\n@ManyToOne(fetch = FetchType.LAZY)\n@NotFound(action = NotFoundAction.IGNORE) // filtered target -> null instead of throw\nprivate Product product;","handlingStrategy":"try-catch","validationCode":"// Before enabling a filter on an association target, count references it would hide\nString sql = \"select count(*) from cart_item ci join product p on p.id = ci.product_id where p.archived = true\";\nlong hidden = ((Number) em.createNativeQuery(sql).getSingleResult()).longValue();\nif (hidden > 0) throw new IllegalStateException(\"restriction would hide \" + hidden + \" referenced products\");","typeGuard":null,"tryCatchPattern":"try {\n    Cart c = em.find(Cart.class, id); // lazy select-fetch of filtered products\n} catch (EntityFilterException e) {\n    // message names the association path; decide: un-filter, ignore (@NotFound(IGNORE)), or skip\n}","preventionTips":["Map associations to filter-restricted entities as @NotFound(action = IGNORE) when absence is expected.","Enable filters as narrowly as possible (per query/session, not globally).","Add tests where a filtered target is dereferenced lazily - that is exactly when this throws."],"tags":["hibernate","orm","filter","lazy-loading","select-fetch","entity-filter-exception"],"backgroundTag":"entity-filtered-by-hibernate-filter","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}