pola-rs/polars · error · ValueError

can not match overlapping patterns when leftmost == True

Error message

can not match overlapping patterns when leftmost == True

What it means

Expr.str.extract_many rejects overlapping=True combined with leftmost=True: the leftmost-first strategy resolves exactly one match per position and cannot simultaneously emit overlapping matches, so the flag combination is contradictory and raises ValueError before any matching runs.

Source

Thrown at py-polars/src/polars/expr/string.py:3011

        ... )
        >>> df.select(pl.col("values").str.extract_many("patterns"))
        shape: (2, 1)
        ┌─────────────────┐
        │ values          │
        │ ---             │
        │ list[str]       │
        ╞═════════════════╡
        │ ["disco"]       │
        │ ["rhap", "ody"] │
        └─────────────────┘

        See Also
        --------
        replace_many
        """
        if overlapping and leftmost:
            msg = "can not match overlapping patterns when leftmost == True"
            raise ValueError(msg)
        patterns_pyexpr = parse_into_expression(patterns, str_as_lit=False)
        return wrap_expr(
            self._pyexpr.str_extract_many(
                patterns_pyexpr, ascii_case_insensitive, overlapping, leftmost
            )
        )

    @unstable()
    def find_many(
        self,
        patterns: IntoExpr,
        *,
        ascii_case_insensitive: bool = False,
        overlapping: bool = False,
        leftmost: bool = False,
    ) -> Expr:
        """
        Use the Aho-Corasick algorithm to find many matches.

View on GitHub (pinned to df599052da)

Solutions

Drop leftmost: .str.extract_many(pats, overlapping=True)
Or drop overlapping: .str.extract_many(pats, leftmost=True)
If you need both behaviors, run two extractions and merge/deduplicate the result lists yourself
Validate forwarded kwargs so the two flags are never both truthy

Example fix

# before
pl.col('s').str.extract_many(pl.col('pats'), overlapping=True, leftmost=True)

# after
pl.col('s').str.extract_many(pl.col('pats'), overlapping=True)
# or
pl.col('s').str.extract_many(pl.col('pats'), leftmost=True)

Defensive patterns

Strategy: validation

Validate before calling

if overlapping and leftmost:
    raise ValueError('choose either overlapping or leftmost, not both')
expr = pl.col('s').str.extract_many(pl.col('pats'), overlapping=overlapping, leftmost=leftmost)

Prevention

Document which matching semantics each call site needs and set only that flag
Do not forward blanket **kwargs into *_many methods
Write a unit test per flag combination you rely on

When it happens

Trigger: .str.extract_many(pl.col('pats'), overlapping=True, leftmost=True); copy-pasting flag combinations from find_many or Aho-Corasick examples; incrementally adding leftmost for deterministic longest-match output while keeping overlapping from an earlier iteration.

Common situations: Tuning multi-pattern matching semantics to mimic Python's re (leftmost-longest); flag dicts forwarded via **kwargs where both keys end up True.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/87e82b37e2740884. Report an issue: GitHub.