{"record":{"id":"e50eb128d20b44c8","repo":"pola-rs/polars","slug":"invalid-scaling-mode-scaling-mode-r","errorCode":null,"errorMessage":"invalid `scaling_mode` {scaling_mode!r}","messagePattern":"invalid `scaling_mode` (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/engine_remote.py","lineNumber":125,"sourceCode":"    labels: list[str] | None\n    \"\"\"Labels attached to the query.\"\"\"\n    config: Mapping[str, Any]\n    \"\"\"Additional options forwarded to the distributed planner.\"\"\"\n\n    def __init__(\n        self,\n        context: pc.ClientContext | None = None,\n        *,\n        scaling_mode: ScalingMode = \"auto\",\n        engine: EngineTypeName = \"auto\",\n        plan_type: PlanTypePreference = \"dot\",\n        n_retries: int = 0,\n        labels: list[str] | str | None = None,\n        **kwargs: Any,\n    ) -> None:\n        if scaling_mode not in _SCALING_MODES:\n            msg = f\"invalid `scaling_mode` {scaling_mode!r}\"\n            raise ValueError(msg)\n        if engine not in _WORKER_ENGINE_NAMES:\n            msg = f\"Invalid engine argument {engine=}\"\n            raise ValueError(msg)\n        if scaling_mode == \"single-node\" and kwargs:\n            msg = (\n                f\"distributed options {sorted(kwargs)!r} are not supported with \"\n                \"`scaling_mode='single-node'`\"\n            )\n            raise ValueError(msg)\n\n        # fail here rather than deep inside a sink\n        import_optional(\n            \"polars_cloud\",\n            err_prefix=\"remote engine requested, but required package\",\n            install_message=\"Please install using the command `pip install polars-cloud`\",\n        )\n\n        self.context = context","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/lazyframe/engine_remote.py#L107-L143","documentation":"`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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Use one of `'auto'`, `'single-node'`, `'distributed'` (exact spelling, hyphenated)","If the value is user-supplied, validate against a set before constructing the engine","For 'run on one machine' semantics choose `'single-node'`; for forcing cluster execution choose `'distributed'`"],"exampleFix":"# before\nengine = pl.RemoteEngine(ctx, scaling_mode='cluster')  # ValueError\n\n# after\nengine = pl.RemoteEngine(ctx, scaling_mode='distributed')","handlingStrategy":"validation","validationCode":"VALID_SCALING_MODES = {'auto', 'single-node', 'distributed'}\n\ndef make_remote_engine(ctx, scaling_mode: str, **kw):\n    if scaling_mode not in VALID_SCALING_MODES:\n        raise ValueError(\n            f'scaling_mode must be one of {sorted(VALID_SCALING_MODES)}, got {scaling_mode!r}'\n        )\n    return pl.RemoteEngine(ctx, scaling_mode=scaling_mode, **kw)","typeGuard":"from typing import TypeGuard\n\ndef is_scaling_mode(value: object) -> TypeGuard[str]:\n    return value in ('auto', 'single-node', 'distributed')","tryCatchPattern":"try:\n    engine = pl.RemoteEngine(ctx, scaling_mode=mode)\nexcept ValueError as e:\n    if 'scaling_mode' in str(e):\n        engine = pl.RemoteEngine(ctx)  # default 'auto'\n    else:\n        raise","preventionTips":["Restrict scaling_mode at your config boundary with an enum or Literal type","Use exactly the hyphenated spellings 'single-node'/'distributed'","Construct the RemoteEngine once at startup so bad values fail fast, not mid-job"],"tags":["polars","remote","cloud","config","valueerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}