{"record":{"id":"a1b3be8a3b272ca8","repo":"pola-rs/polars","slug":"invalid-predicate-for-filter-err","errorCode":null,"errorMessage":"invalid predicate for `filter`: {err}","messagePattern":"invalid predicate for `filter`: (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/frame.py","lineNumber":4695,"sourceCode":"\n            # note: identify masks separately from predicates\n            if is_bool_sequence(p, include_series=True):\n                boolean_masks.append(pl.Series(p, dtype=Boolean))\n            elif (\n                (is_seq := is_sequence(p))\n                and any(not isinstance(x, pl.Expr) for x in p)\n            ) or (\n                not is_seq\n                and not isinstance(p, pl.Expr)\n                and not (isinstance(p, str) and p in self.collect_schema())\n            ):\n                err = (\n                    f\"Series(…, dtype={p.dtype})\"\n                    if isinstance(p, pl.Series)\n                    else repr(p)\n                )\n                msg = f\"invalid predicate for `filter`: {err}\"\n                raise TypeError(msg)\n            else:\n                all_predicates.extend(\n                    wrap_expr(x) for x in parse_into_list_of_expressions(p)\n                )\n\n        # unpack equality constraints from kwargs\n        all_predicates.extend(\n            F.col(name).eq(value) for name, value in constraints.items()\n        )\n        if not (all_predicates or boolean_masks):\n            msg = \"at least one predicate or constraint must be provided\"\n            raise TypeError(msg)\n\n        # if multiple predicates, combine as 'horizontal' expression\n        combined_predicate = (\n            (\n                F.all_horizontal(*all_predicates)\n                if len(all_predicates) > 1","sourceCodeStart":4677,"sourceCodeEnd":4713,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/lazyframe/frame.py#L4677-L4713","documentation":"LazyFrame.filter() accepts Polars expressions, strings naming a schema column, or boolean masks in supported positions. If a predicate is (or a sequence contains) something else — typically a pl.Series or plain Python value — polars raises TypeError showing the offending object. String predicates must name an existing column in collect_schema().","triggerScenarios":"lf.filter(pl.Series([True, False])) on a LazyFrame (Series positional masks are not valid lazily); lf.filter('nonexistent_column'); lf.filter([pl.col('a') > 1, 'or']) mixing invalid items; passing a numpy array or plain bool.","commonSituations":"Reusing DataFrame filter code (where boolean Series masks work) on lazy frames; dynamic predicate lists built from user input where a None or raw value sneaks in; column renames making a string predicate stale.","solutions":["Convert Series masks to expressions: lf.filter(pl.col('a').is_in(series)) or compare directly","For string predicates, confirm the name exists in lf.collect_schema().names()","Validate each predicate with isinstance(p, pl.Expr) before adding it to a dynamic list","Use keyword constraints for equality: lf.filter(country='NL') instead of raw values"],"exampleFix":"# before\nmask = pl.Series([True, False, True])\nlf2 = lf.filter(mask)\n\n# after\nlf2 = lf.filter(pl.col('a') > 5)","handlingStrategy":"type-guard","validationCode":"import polars as pl\nschema_names = set(lf.collect_schema().names())\npreds = [p for p in raw_predicates if isinstance(p, pl.Expr) or (isinstance(p, str) and p in schema_names)]\nif preds:\n    lf = lf.filter(*preds)","typeGuard":"def is_valid_predicate(p, schema_names: set[str]) -> bool:\n    import polars as pl\n    return isinstance(p, pl.Expr) or (isinstance(p, str) and p in schema_names)","tryCatchPattern":"try:\n    lf = lf.filter(*preds)\nexcept TypeError as e:\n    if 'invalid predicate' in str(e):\n        # log offending predicates and fall back to expression-only set\n        lf = lf.filter(*(p for p in preds if isinstance(p, pl.Expr)))\n    else:\n        raise","preventionTips":["Build predicates exclusively with pl.col() expressions","Never pass boolean Series/numpy arrays to LazyFrame.filter","Validate string predicates against collect_schema() before use"],"tags":["polars","lazyframe","filter","predicates","typeerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}