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() can either scan for all overlapping matches or return the leftmost non-overlapping match per pattern, but not both: `overlapping=True` and `leftmost=True` are contradictory modes. polars raises ValueError up front when both are set.

Solutions

1. Set `leftmost=False` (default) to keep overlapping matching
2. Or set `overlapping=False` if you need leftmost match semantics
3. Decide which mode you need: exhaustive overlap vs leftmost-per-pattern

Example fix

// before
pl.col('x').str.extract_many(['ab', 'bc'], overlapping=True, leftmost=True)
// after
pl.col('x').str.extract_many(['ab', 'bc'], overlapping=True)

if overlapping and leftmost:
    raise ValueError('overlapping and leftmost are mutually exclusive')

try:
    expr = pl.col('x').str.extract_many(pats, overlapping=True, leftmost=True)
except ValueError:
    expr = pl.col('x').str.extract_many(pats, overlapping=True)

When it happens

Trigger: Calling `pl.col('x').str.extract_many(patterns, overlapping=True, leftmost=True)`.

Common situations: Copy-pasting keyword arguments from docs of both modes; wanting exhaustive matches while also assuming leftmost ordering semantics.

Related errors

• arr.dot query vector must be one-dimensional
• cannot specify both `n` and `fraction`
• cannot use credential_provider when passing a DeltaTable…
• `columns` arg should only have unique values, got
• `dtype` must be of type

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

Appendix: source

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

        ... )
        >>> 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 fe841f959e)