{"record":{"id":"5da86fd51b622441","repo":"pola-rs/polars","slug":"invalid-engine","errorCode":null,"errorMessage":"invalid engine","messagePattern":"invalid engine","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/config.py","lineNumber":1606,"sourceCode":"\n        >>> pl.Config.set_engine_affinity(\n        ...     pl.GPUEngine(device=1, raise_on_fail=True)\n        ... )  # doctest: +SKIP\n\n        Raises\n        ------\n        ValueError: if engine is not recognised.\n        \"\"\"\n        if isinstance(engine, Engine):\n            # Object affinities are Python-only; clear the named affinity.\n            os.environ.pop(\"POLARS_ENGINE_AFFINITY\", None)\n            set_engine_affinity_override(engine)\n            plr.config_reload_env_var(\"POLARS_ENGINE_AFFINITY\")\n            return cls\n\n        if engine not in {*SUPPORTED_ENGINE_NAMES, None}:\n            msg = \"invalid engine\"\n            raise ValueError(msg)\n        if engine is None:\n            os.environ.pop(\"POLARS_ENGINE_AFFINITY\", None)\n        else:\n            os.environ[\"POLARS_ENGINE_AFFINITY\"] = engine\n        set_engine_affinity_override(None)\n        plr.config_reload_env_var(\"POLARS_ENGINE_AFFINITY\")\n\n        return cls\n\n    @classmethod\n    def enable_monitoring(\n        cls,\n        active: bool | None = True,\n        *,\n        workspace: str | None = None,\n        organization: str | None = None,\n    ) -> type[Config]:\n        \"\"\"","sourceCodeStart":1588,"sourceCodeEnd":1624,"githubUrl":"https://github.com/pola-rs/polars/blob/68506541d2de983056c9eb244e1ea05fab377dfc/py-polars/src/polars/config.py#L1588-L1624","documentation":"`pl.Config.set_engine_affinity(engine)` accepts an `Engine` object, None, or one of the names in SUPPORTED_ENGINE_NAMES: 'auto', 'in-memory', 'streaming', 'gpu'. Any other string raises a bare ValueError('invalid engine'). An `Engine` instance sets a Python-only object affinity; a valid name sets the POLARS_ENGINE_AFFINITY env var.","triggerScenarios":"`pl.Config.set_engine_affinity('polars')`, 'cpu', 'auto-detect', or a misspelled name; passing an engine string valid elsewhere (e.g. a backend name from another library).","commonSituations":"Assuming arbitrary engine strings are accepted; confusing the global affinity with per-call `lf.collect(engine=...)`; GPU users guessing the name ('cuda' instead of 'gpu').","solutions":["Use one of 'auto', 'in-memory', 'streaming', 'gpu' (or an `Engine` instance).","For a one-off engine choice, pass it at call time: `lf.collect(engine='streaming')` instead of setting a global affinity.","For the GPU engine use the name 'gpu'."],"exampleFix":"# before\npl.Config.set_engine_affinity(\"cuda\")  # ValueError: invalid engine\n\n# after\npl.Config.set_engine_affinity(\"gpu\")","handlingStrategy":"validation","validationCode":"SUPPORTED = frozenset({\"auto\", \"in-memory\", \"streaming\", \"gpu\"})\n\ndef set_engine(engine: str | None) -> None:\n    if engine is not None and engine not in SUPPORTED:\n        raise ValueError(f\"engine must be one of {sorted(SUPPORTED)}, got {engine!r}\")\n    pl.Config.set_engine_affinity(engine)","typeGuard":"from typing import Literal, TypeGuard\n\nEngineName = Literal[\"auto\", \"in-memory\", \"streaming\", \"gpu\"]\n\ndef is_engine_name(value: str) -> TypeGuard[EngineName]:\n    return value in {\"auto\", \"in-memory\", \"streaming\", \"gpu\"}","tryCatchPattern":null,"preventionTips":["Use a Literal type for engine names in config loaders so bad values fail type-check.","Prefer per-call engine selection (lf.collect(engine=...)) over the global affinity."],"tags":["config","engine","validation","polars"],"backgroundTag":"invalid-engine-name","analyzedSha":"68506541d2de983056c9eb244e1ea05fab377dfc","analyzedAt":"2026-08-19T12:15:06.350Z","contentChangedAt":"2026-08-19T12:15:06.350Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}