What causes "collect() got an unexpected keyword argument '{k}'" in pola-rs/polars?

Replace collect(streaming=True) with collect(engine='streaming')

pola-rs/polars · error · TypeError

collect() got an unexpected keyword argument '{k}'

Error message

collect() got an unexpected keyword argument '{k}'

What it means

LazyFrame.collect() explicitly rejects any **kwargs except the private post_opt_callback. Parameters like engine, optimizations, and background are named parameters and must be passed as such; anything else routed through **kwargs raises TypeError. This guard was added to catch silently-ignored typos and removed parameters (e.g. the old no_optimization kwarg).

Source

Thrown at py-polars/src/polars/lazyframe/frame.py:2584

        ...     engine=pl.GPUEngine(device=1)
        ... )  # doctest: +SKIP
        shape: (3, 3)
        ┌─────┬─────┬─────┐
        │ a   ┆ b   ┆ c   │
        │ --- ┆ --- ┆ --- │
        │ str ┆ i64 ┆ i64 │
        ╞═════╪═════╪═════╡
        │ b   ┆ 11  ┆ 10  │
        │ a   ┆ 4   ┆ 10  │
        │ c   ┆ 6   ┆ 1   │
        └─────┴─────┴─────┘
        """
        for k in _kwargs:
            if k not in (  # except "private" kwargs
                "post_opt_callback",
            ):
                error_msg = f"collect() got an unexpected keyword argument '{k}'"
                raise TypeError(error_msg)

        engine_ = _select_engine(engine)
        post_opt_callback = _kwargs.get("post_opt_callback")

        return engine_.collect(
            self,
            optimizations=optimizations,
            background=background,
            post_opt_callback=post_opt_callback,
        )

    @overload
    def collect_async(
        self,
        *,
        gevent: Literal[True],
        engine: EngineType = "auto",
        optimizations: QueryOptFlags = DEFAULT_QUERY_OPT_FLAGS,

View on GitHub (pinned to df599052da)

Solutions

Replace collect(streaming=True) with collect(engine='streaming')
Replace no_optimization=True with optimizations=Optimizations.none() (named arg)
Filter forwarded **options dicts to the known parameter names before calling collect
Run python -c 'import inspect; print(inspect.signature(lf.collect))' after upgrade to see the current signature

Example fix

# before
lf.collect(streaming=True)

# after
lf.collect(engine='streaming')

Defensive patterns

Strategy: validation

Validate before calling

import inspect
sig = inspect.signature(lf.collect)
kwargs = {k: v for k, v in kwargs.items() if k in sig.parameters}
df = lf.collect(**kwargs)

Type guard

def is_collect_parameter(k: str) -> bool:
    import inspect
    return k in inspect.signature(lf.collect).parameters

Try / catch

try:
    df = lf.collect(**opts)
except TypeError as e:
    if 'unexpected keyword' in str(e):
        raise ValueError(f'invalid collect options: {opts}') from e
    raise

Prevention

Replace removed kwargs (streaming, no_optimization) with engine/optimizations
Keep an explicit list of allowed collect options and filter **kwargs against it
Add a smoke test that calls collect with your production options dict

When it happens

Trigger: lf.collect(no_optimization=True) (removed parameter), lf.collect(streaming=True) (removed in favor of engine), or lf.collect(**user_options) where user_options contains stale keys. Refactoring code from polars <1.0 to current versions.

Common situations: Version upgrades from polars 0.20/1.x where collect(streaming=True) or no_optimization were valid; generic option dicts shared across APIs.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/148d3a72d6833e05. Report an issue: GitHub.