pola-rs/polars · error · ValueError

unrecognised frame type: {qualified_type_name(obj)}

Error message

unrecognised frame type: {qualified_type_name(obj)}

What it means

_ensure_lazyframe in the SQL context only accepts DataFrame, LazyFrame, Series, pandas DataFrame/Series, PyCapsule, or pyarrow Table/RecordBatch; any other registered object type reaches the terminal guard and raises with its qualified type name. Means you registered/framed an unsupported object in a SQL context.

Source

Thrown at py-polars/src/polars/sql/context.py:77

def _ensure_lazyframe(obj: Any) -> LazyFrame:
    """Return LazyFrame from compatible input."""
    if isinstance(obj, (DataFrame, LazyFrame)):
        return obj.lazy()
    elif isinstance(obj, Series):
        return obj.to_frame().lazy()
    elif _check_for_pandas(obj) and isinstance(obj, (pd.DataFrame, pd.Series)):
        if isinstance(frame := from_pandas(obj), Series):
            frame = frame.to_frame()
        return frame.lazy()
    elif is_pycapsule(obj) or (
        _check_for_pyarrow(obj) and isinstance(obj, (pa.Table, pa.RecordBatch))
    ):
        return DataFrame(obj).lazy()  # type: ignore[union-attr]
    else:
        msg = f"unrecognised frame type: {qualified_type_name(obj)}"
        raise ValueError(msg)


def _get_frame_locals(
    *,
    all_compatible: bool,
    n_objects: int | None = None,
    named: str | Collection[str] | Callable[[str], bool] | None = None,
) -> dict[str, Any]:
    """Return compatible frame objects from the local stack."""
    of_type = _compatible_frame if all_compatible else (DataFrame, LazyFrame, Series)
    return _get_stack_locals(of_type=of_type, n_objects=n_objects, named=named)  # type: ignore[arg-type]


class SQLContext(Generic[FrameType]):
    """
    Run SQL queries against DataFrame, LazyFrame, and Series data.

    .. warning::

View on GitHub (pinned to 5d8ebabf11)

Solutions

1. Register objects of a recognised frame type (DataFrame, LazyFrame, or a SQLContext-compatible mapping); convert the object before registering.

When it happens

Trigger: Thrown at py-polars/src/polars/sql/context.py:77 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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