pola-rs/polars · error · ValueError

invalid `scaling_mode` {scaling_mode!r}

Error message

invalid `scaling_mode` {scaling_mode!r}

What it means

`RemoteEngine.__init__` (engine_remote.py:123) validates `scaling_mode` against the `ScalingMode` literal before doing anything else, so an invalid value fails fast at engine construction instead of deep inside a query. Valid values are `'auto'`, `'single-node'`, and `'distributed'`. `'auto'` runs distributed only if the cluster has more than one node.

Source

Thrown at py-polars/src/polars/lazyframe/engine_remote.py:125

    labels: list[str] | None
    """Labels attached to the query."""
    config: Mapping[str, Any]
    """Additional options forwarded to the distributed planner."""

    def __init__(
        self,
        context: pc.ClientContext | None = None,
        *,
        scaling_mode: ScalingMode = "auto",
        engine: EngineTypeName = "auto",
        plan_type: PlanTypePreference = "dot",
        n_retries: int = 0,
        labels: list[str] | str | None = None,
        **kwargs: Any,
    ) -> None:
        if scaling_mode not in _SCALING_MODES:
            msg = f"invalid `scaling_mode` {scaling_mode!r}"
            raise ValueError(msg)
        if engine not in _WORKER_ENGINE_NAMES:
            msg = f"Invalid engine argument {engine=}"
            raise ValueError(msg)
        if scaling_mode == "single-node" and kwargs:
            msg = (
                f"distributed options {sorted(kwargs)!r} are not supported with "
                "`scaling_mode='single-node'`"
            )
            raise ValueError(msg)

        # fail here rather than deep inside a sink
        import_optional(
            "polars_cloud",
            err_prefix="remote engine requested, but required package",
            install_message="Please install using the command `pip install polars-cloud`",
        )

        self.context = context

View on GitHub (pinned to df599052da)

Solutions

1. Use one of `'auto'`, `'single-node'`, `'distributed'` (exact spelling, hyphenated)
2. If the value is user-supplied, validate against a set before constructing the engine
3. For 'run on one machine' semantics choose `'single-node'`; for forcing cluster execution choose `'distributed'`

Example fix

# before
engine = pl.RemoteEngine(ctx, scaling_mode='cluster')  # ValueError

# after
engine = pl.RemoteEngine(ctx, scaling_mode='distributed')

VALID_SCALING_MODES = {'auto', 'single-node', 'distributed'}

def make_remote_engine(ctx, scaling_mode: str, **kw):
    if scaling_mode not in VALID_SCALING_MODES:
        raise ValueError(
            f'scaling_mode must be one of {sorted(VALID_SCALING_MODES)}, got {scaling_mode!r}'
        )
    return pl.RemoteEngine(ctx, scaling_mode=scaling_mode, **kw)

from typing import TypeGuard

def is_scaling_mode(value: object) -> TypeGuard[str]:
    return value in ('auto', 'single-node', 'distributed')

try:
    engine = pl.RemoteEngine(ctx, scaling_mode=mode)
except ValueError as e:
    if 'scaling_mode' in str(e):
        engine = pl.RemoteEngine(ctx)  # default 'auto'
    else:
        raise

When it happens

Trigger: `pl.RemoteEngine(context, scaling_mode='cluster')`, `'single_node'`, `'multi-node'`, or any string not in `{'auto','single-node','distributed'}`. The value is checked before the `polars_cloud` import, so this fires even without the package installed.

Common situations: Scaling mode loaded from a config file or CLI flag with free-form text; vocabulary drift from other distributed systems ('cluster', 'local', 'vertical'); exploratory code guessing parameter names.

Related errors

• Invalid engine argument {engine=}
• distributed options {sorted(kwargs)!r} are not supported wit
• `{name}` is not supported by the remote engine
• DataFrame `how` must be one of {{{allowed}}}, got {how!r}
• Invalid engine argument {engine=}

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