pola-rs/polars · error · ValueError

invalid engine

Error message

invalid engine

What it means

`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.

Source

Thrown at py-polars/src/polars/config.py:1606

        >>> pl.Config.set_engine_affinity(
        ...     pl.GPUEngine(device=1, raise_on_fail=True)
        ... )  # doctest: +SKIP

        Raises
        ------
        ValueError: if engine is not recognised.
        """
        if isinstance(engine, Engine):
            # Object affinities are Python-only; clear the named affinity.
            os.environ.pop("POLARS_ENGINE_AFFINITY", None)
            set_engine_affinity_override(engine)
            plr.config_reload_env_var("POLARS_ENGINE_AFFINITY")
            return cls

        if engine not in {*SUPPORTED_ENGINE_NAMES, None}:
            msg = "invalid engine"
            raise ValueError(msg)
        if engine is None:
            os.environ.pop("POLARS_ENGINE_AFFINITY", None)
        else:
            os.environ["POLARS_ENGINE_AFFINITY"] = engine
        set_engine_affinity_override(None)
        plr.config_reload_env_var("POLARS_ENGINE_AFFINITY")

        return cls

    @classmethod
    def enable_monitoring(
        cls,
        active: bool | None = True,
        *,
        workspace: str | None = None,
        organization: str | None = None,
    ) -> type[Config]:
        """

View on GitHub (pinned to 68506541d2)

Solutions

1. Use one of 'auto', 'in-memory', 'streaming', 'gpu' (or an `Engine` instance).
2. For a one-off engine choice, pass it at call time: `lf.collect(engine='streaming')` instead of setting a global affinity.
3. For the GPU engine use the name 'gpu'.

Example fix

# before
pl.Config.set_engine_affinity("cuda")  # ValueError: invalid engine

# after
pl.Config.set_engine_affinity("gpu")

SUPPORTED = frozenset({"auto", "in-memory", "streaming", "gpu"})

def set_engine(engine: str | None) -> None:
    if engine is not None and engine not in SUPPORTED:
        raise ValueError(f"engine must be one of {sorted(SUPPORTED)}, got {engine!r}")
    pl.Config.set_engine_affinity(engine)

from typing import Literal, TypeGuard

EngineName = Literal["auto", "in-memory", "streaming", "gpu"]

def is_engine_name(value: str) -> TypeGuard[EngineName]:
    return value in {"auto", "in-memory", "streaming", "gpu"}

When it happens

Trigger: `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).

Common situations: 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').

Related errors

• `separator` must be a single character; found {separator!r}
• number of characters must be > 0
• invalid alignment: {format!r}
• invalid table format name: {format!r} Expected one of: {', '
• limit should be positive

AI-assisted analysis of pola-rs/polars@68506541d2 (2026-08-19). Data as JSON: /api/errors/5da86fd51b622441. Report an issue: GitHub.