{"record":{"id":"c56bcb2babb087ca","repo":"pola-rs/polars","slug":"invalid-engine-argument-engine","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_config.py","lineNumber":76,"sourceCode":"def set_engine_affinity_override(engine: Engine | None) -> None:\n    \"\"\"Set the configured engine override.\"\"\"\n    global _ENGINE_AFFINITY_OVERRIDE\n    _ENGINE_AFFINITY_OVERRIDE = engine\n\n\ndef _eager_engine() -> Engine:\n    \"\"\"Return the engine used for internal eager operations.\"\"\"\n    return _IN_MEMORY_ENGINE\n\n\ndef _engine_from_name(engine: EngineTypeName) -> Engine:\n    \"\"\"Resolve an explicit engine name without applying the configured affinity.\"\"\"\n    if engine == \"gpu\":\n        return GPUEngine()\n\n    if (selected := _ENGINE_BY_NAME.get(engine)) is None:\n        msg = f\"Invalid engine argument {engine=}\"\n        raise ValueError(msg)\n    return selected\n\n\ndef _select_engine(engine: EngineType) -> Engine:\n    \"\"\"\n    Resolve an engine argument or configured affinity to an `Engine`.\n\n    An `\"auto\"` affinity remains unresolved for Rust to select at execution time.\n    \"\"\"\n    if isinstance(engine, Engine):\n        return engine\n\n    if engine == \"auto\":\n        if _ENGINE_AFFINITY_OVERRIDE is not None:\n            return _ENGINE_AFFINITY_OVERRIDE\n        engine = get_engine_affinity()\n\n    return _engine_from_name(engine)","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/lazyframe/engine_config.py#L58-L94","documentation":"`_engine_from_name` (engine_config.py:74) resolves an engine name string to an `Engine` instance and raises ValueError for any name not in the registry. Accepted names are `'auto'`, `'in-memory'`, `'streaming'`, `'gpu'`, plus the legacy alias `'cpu'` (mapped to in-memory). Note that `'remote'` is not a name — the remote engine must be passed as an object, e.g. `pl.RemoteEngine()`. The check applies wherever `engine=` accepts a string (`collect`, `execute`, `sink_*`, scan functions, `pl.collect_all`).","triggerScenarios":"`lf.collect(engine='remote')`, `engine='in_memory'`/`'streaming-engine'` (typos, underscores), `engine='cpu-force'`, or any string not in `{'auto','in-memory','streaming','gpu','cpu'}`. Also raised when a name read from environment/config is passed through unvalidated.","commonSituations":"Configuration-driven engine selection (env var, YAML) where a bad or stale value flows into `engine=`; renaming churn across Polars versions (older releases used different engine vocabularies); attempting to select Polars Cloud by string instead of an engine object.","solutions":["Fix the name to one of `'auto' | 'in-memory' | 'streaming' | 'gpu'` (legacy `'cpu'` still accepted)","For remote execution pass an instance: `engine=pl.RemoteEngine(...)` — never the string `'remote'`","If the value comes from config, validate it against `polars.lazyframe.engine_config.SUPPORTED_ENGINE_NAMES` before use","Check for leading/trailing whitespace or underscores in dynamically built names"],"exampleFix":"# before\nlf.collect(engine='remote')  # ValueError: Invalid engine argument\n\n# after\nlf.collect(engine=pl.RemoteEngine())\n# or a valid name:\nlf.collect(engine='streaming')","handlingStrategy":"validation","validationCode":"from polars.lazyframe.engine_config import SUPPORTED_ENGINE_NAMES\n\nVALID_ENGINE_NAMES = set(SUPPORTED_ENGINE_NAMES) | {'cpu'}  # 'cpu' is a legacy alias\n\ndef resolve_engine_name(name: str) -> str:\n    if name not in VALID_ENGINE_NAMES:\n        raise ValueError(\n            f'unknown engine {name!r}; expected one of {sorted(VALID_ENGINE_NAMES)}'\n        )\n    return name\n\nlf.collect(engine=resolve_engine_name(cfg['engine']))","typeGuard":"from typing import TypeGuard\nfrom polars.lazyframe.engine_config import SUPPORTED_ENGINE_NAMES\n\n_VALID = set(SUPPORTED_ENGINE_NAMES) | {'cpu'}\n\ndef is_engine_name(name: object) -> TypeGuard[str]:\n    return isinstance(name, str) and name in _VALID","tryCatchPattern":"try:\n    df = lf.collect(engine=engine_name)\nexcept ValueError as e:\n    if 'Invalid engine argument' in str(e):\n        df = lf.collect(engine='streaming')  # safe default\n    else:\n        raise","preventionTips":["Validate engine names from env/config/CLI against SUPPORTED_ENGINE_NAMES before use","Pass engine objects (pl.RemoteEngine()) for remote, never the string 'remote'","Use a Literal['auto','in-memory','streaming','gpu'] type for engine parameters in your own APIs"],"tags":["polars","engine","config","valueerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}