pola-rs/polars · error · TypeError

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

Error message

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

What it means

LazyFrame.profile() no longer accepts arbitrary **kwargs; the only 'private' kwarg still honored is post_opt_callback. Anything else (e.g. the old engine/optimizations-style keywords or deprecated aliases like collect-related args) raises TypeError. This mirrors the same guard on collect().

Source

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

         │ c   ┆ 6   ┆ 1   │
         └─────┴─────┴─────┘,
         shape: (3, 3)
         ┌─────────────────────────┬───────┬──────┐
         │ node                    ┆ start ┆ end  │
         │ ---                     ┆ ---   ┆ ---  │
         │ str                     ┆ u64   ┆ u64  │
         ╞═════════════════════════╪═══════╪══════╡
         │ optimization            ┆ 0     ┆ 5    │
         │ group_by_partitioned(a) ┆ 5     ┆ 470  │
         │ sort(a)                 ┆ 475   ┆ 1964 │
         └─────────────────────────┴───────┴──────┘)
        """
        for k in _kwargs:
            if k not in (  # except "private" kwargs
                "post_opt_callback",
            ):
                error_msg = f"profile() got an unexpected keyword argument '{k}'"
                raise TypeError(error_msg)
        engine = _select_engine(engine)

        optimizations = optimizations.__copy__()
        ldf = self._ldf.with_optimizations(optimizations._pyoptflags)

        callback = (
            engine._post_opt_callback(background=False, eager=False)
            if isinstance(engine, GPUEngine)
            else None
        )
        if _kwargs.get("post_opt_callback") is not None:
            callback = _kwargs.get("post_opt_callback")
        df_py, timings_py = ldf.profile(callback)
        (df, timings) = wrap_df(df_py), wrap_df(timings_py)

        if show_plot:
            import_optional(
                "matplotlib",

View on GitHub (pinned to df599052da)

Solutions

1. Remove the invalid kwarg; pass supported options as named parameters (engine=..., optimizations=...) instead of via **kwargs
2. If forwarding a dict, filter it to known keys first
3. Keep only post_opt_callback inside **kwargs
4. Check the current signature with help(lf.profile) after upgrading polars

Example fix

# before
lf.profile(optimizations='none')  # wrong: goes into **_kwargs

# after
from polars.optimizer import Optimizations
lf.profile(optimizations=Optimizations.none())

allowed = {'post_opt_callback'}
extra = {k: v for k, v in kwargs.items() if k in allowed}
lf.profile(**extra, engine=engine)

def is_supported_profile_kwarg(k: str) -> bool:
    return k == 'post_opt_callback'

When it happens

Trigger: Calling lf.profile(engine='streaming') or lf.profile(no_optimization=True) — kwargs that older polars versions accepted or that belong to collect()'s named parameters. Passing leftovers from **options dicts built for other calls.

Common situations: Upgrading polars across versions where collect/profile kwargs were cleaned up; forwarding a shared **options dict to multiple frame methods.

Related errors

• collect() got an unexpected keyword argument '{k}'
• Expected Polars expression or object convertible to one, got
• negative stop is not supported for lazy slices
• negative stride is not supported in conjunction with start+s
• the given slice {s!r} is not supported by lazy computation\n

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