{"record":{"id":"b4beb07fecae3666","repo":"pola-rs/polars","slug":"invalid-engine-argument-engine-b4beb0","errorCode":null,"errorMessage":"Invalid engine argument {engine=}","messagePattern":"Invalid engine argument (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/engine_remote.py","lineNumber":128,"sourceCode":"    \"\"\"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\n        self.scaling_mode = scaling_mode\n        self.engine = engine\n        self.plan_type = plan_type","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/lazyframe/engine_remote.py#L110-L146","documentation":"`RemoteEngine.__init__` (engine_remote.py:126) validates its `engine` keyword — the preferred worker engine hint that also controls plan rendering — against the `EngineTypeName` literal `{'auto','in-memory','streaming','gpu'}`. Unlike the global engine-name resolver, the legacy alias `'cpu'` is NOT accepted here because validation uses `get_args(EngineTypeName)`. The check runs at construction time, before the `polars_cloud` dependency is imported.","triggerScenarios":"`pl.RemoteEngine(ctx, engine='cpu')` (legacy alias rejected here), `engine='remote'`, or any typo such as `'gpu-cuda'`/`'streaming-engine'`. Only the four literal names pass.","commonSituations":"Reusing a global engine-name string (that legitimately contains 'cpu') as the RemoteEngine worker hint; copy-pasting engine values between `lf.collect(engine=...)` and `RemoteEngine(engine=...)` without noticing the stricter set; config files shared across tools.","solutions":["Use `'auto'`, `'in-memory'`, `'streaming'`, or `'gpu'` for the RemoteEngine `engine` keyword","Replace legacy `'cpu'` with `'in-memory'` when targeting remote workers","Validate against `{'auto','in-memory','streaming','gpu'}` (not the global `SUPPORTED_ENGINE_NAMES` semantics) when the value is dynamic"],"exampleFix":"# before\nengine = pl.RemoteEngine(ctx, engine='cpu')  # ValueError\n\n# after\nengine = pl.RemoteEngine(ctx, engine='in-memory')","handlingStrategy":"validation","validationCode":"# Stricter than the global engine registry: no 'cpu' alias here\nREMOTE_WORKER_ENGINES = ('auto', 'in-memory', 'streaming', 'gpu')\n\ndef make_remote_engine(ctx, engine: str = 'auto', **kw):\n    if engine not in REMOTE_WORKER_ENGINES:\n        raise ValueError(f'worker engine must be one of {REMOTE_WORKER_ENGINES}, got {engine!r}')\n    return pl.RemoteEngine(ctx, engine=engine, **kw)","typeGuard":"from typing import TypeGuard\n\ndef is_worker_engine_name(value: object) -> TypeGuard[str]:\n    return value in ('auto', 'in-memory', 'streaming', 'gpu')","tryCatchPattern":"try:\n    engine = pl.RemoteEngine(ctx, engine=worker)\nexcept ValueError as e:\n    if 'Invalid engine argument' in str(e):\n        engine = pl.RemoteEngine(ctx, engine='auto')\n    else:\n        raise","preventionTips":["Remember RemoteEngine's engine= accepts only the four literal names; 'cpu' is rejected","Do not reuse global engine-name strings as worker-engine hints without mapping","Type the parameter as Literal['auto','in-memory','streaming','gpu'] in your wrappers"],"tags":["polars","remote","cloud","engine","config","valueerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}