pola-rs/polars · error · ValueError

limit should be positive

Error message

limit should be positive

What it means

`pl.Config.set_expr_depth_warning(limit)` sets POLARS_MAX_EXPR_DEPTH, the expression-nesting depth allowed before polars warns about stack-overflow risk. Negative limits are rejected; note the message says 'positive' but the guard is `limit < 0`, so 0 is accepted. There is no negative value that disables the warning.

Source

Thrown at py-polars/src/polars/config.py:1537

        UnstableWarning: `qcut` is considered unstable. It may be changed at any point without it being considered a breaking change.
        """  # noqa: W505
        if active is None:
            os.environ.pop("POLARS_WARN_UNSTABLE", None)
        else:
            os.environ["POLARS_WARN_UNSTABLE"] = str(int(active))
        plr.config_reload_env_var("POLARS_WARN_UNSTABLE")
        return cls

    @classmethod
    def set_expr_depth_warning(cls, limit: int) -> type[Config]:
        """
        Set the expression depth that Polars will accept without triggering a warning.

        Having too deep expressions (several 1000s) can lead to overflowing the stack and might be worth a refactor.
        """  # noqa: W505
        if limit < 0:
            msg = "limit should be positive"
            raise ValueError(msg)

        os.environ["POLARS_MAX_EXPR_DEPTH"] = str(limit)
        plr.config_reload_env_var("POLARS_MAX_EXPR_DEPTH")
        return cls

    @classmethod
    def set_engine_affinity(cls, engine: EngineType | None = None) -> type[Config]:
        """
        Set which engine to use by default.

        Parameters
        ----------
        engine : {None, 'auto', 'in-memory', 'streaming', 'gpu'}
            The default execution engine Polars will attempt to use
            when calling `.collect()`. However, the query is not
            guaranteed to execute with the specified engine.

            An :class:`Engine` object may also be used to configure the default. Engine

View on GitHub (pinned to 68506541d2)

Solutions

1. Pass 0 or a large positive value (e.g. 100_000) to effectively stop the warning.
2. Better long-term fix: refactor the deep expression into intermediate columns or several with_columns steps.

Example fix

# before
pl.Config.set_expr_depth_warning(-1)  # ValueError: limit should be positive

# after
pl.Config.set_expr_depth_warning(100_000)

def set_expr_depth(limit: int | None) -> None:
    if limit is not None and limit < 0:
        raise ValueError("expression depth limit must be >= 0")
    pl.Config.set_expr_depth_warning(limit if limit is not None else 100_000)

When it happens

Trigger: `pl.Config.set_expr_depth_warning(-1)` hoping to silence the warning; passing a computed depth that went negative.

Common situations: Deeply chained expressions (long .with_columns / string op chains) triggering the warning; users trying to turn the warning off with a sentinel value.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• `separator` must be a single character; found {separator!r}
• number of characters must be > 0
• invalid alignment: {format!r}
• invalid table format name: {format!r} Expected one of: {', '
• invalid engine

AI-assisted analysis of pola-rs/polars@68506541d2 (2026-08-19). Data as JSON: /api/errors/c44598656f5be26c. Report an issue: GitHub.