{"record":{"id":"a64f61e3b38e20ad","repo":"pola-rs/polars","slug":"expected-pandas-dataframe-or-series-got-qualifie","errorCode":null,"errorMessage":"expected pandas DataFrame or Series, got {qualified_type_name(data)!r}","messagePattern":"expected pandas DataFrame or Series, got (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/convert/general.py","lineNumber":729,"sourceCode":"    \"\"\"\n    if include_index and isinstance(data, pd.Series):\n        data = data.reset_index()\n\n    if isinstance(data, (pd.Series, pd.Index, pd.DatetimeIndex)):\n        return wrap_s(pandas_to_pyseries(\"\", data, nan_to_null=nan_to_null))\n    elif isinstance(data, pd.DataFrame):\n        return wrap_df(\n            pandas_to_pydf(\n                data,\n                schema_overrides=schema_overrides,\n                rechunk=rechunk,\n                nan_to_null=nan_to_null,\n                include_index=include_index,\n            )\n        )\n    else:\n        msg = f\"expected pandas DataFrame or Series, got {qualified_type_name(data)!r}\"\n        raise TypeError(msg)\n\n\n@dataclass(frozen=True, slots=True)\nclass _TablePatterns:\n    \"\"\"Format-specific regex patterns for table parsing.\"\"\"\n\n    cell_edge: re.Pattern[str]\n    cell_split: re.Pattern[str]\n    header_div: re.Pattern[str]\n    row_div: re.Pattern[str]\n    rstrip_chars: str\n\n\n_TABLE_PATTERNS_CACHE: dict[TableRepr, _TablePatterns] = {}\n\n\ndef _build_table_patterns(table_repr: TableRepr) -> _TablePatterns:\n    if table_repr is TableRepr.UTF8:","sourceCodeStart":711,"sourceCodeEnd":747,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/convert/general.py#L711-L747","documentation":"Raised by polars.from_pandas when the object passed as `data` is neither a pandas DataFrame nor a pandas Series. The function is the dedicated pandas bridge; after the pd.DataFrame/pd.Series isinstance checks fail, the final else branch reports the qualified type name of whatever was passed. It exists to stop silently mis-interpreting array-likes or other library objects through pandas conversion.","triggerScenarios":"Calling pl.from_pandas() with a numpy ndarray, a plain Python list/dict, a pyarrow.Table, None, a pandas.Index, a modin/duckdb/pyspark object, or any non-pandas iterable. Any code path that reaches the else branch (not isinstance(data, pd.DataFrame)) with a non-Series raises.","commonSituations":"Migrating pandas code and swapping pd.DataFrame(...) for pl.from_pandas(...) without changing the input; passing an Arrow table or numpy matrix because both are 'table-like'; feeding a .to_numpy() result or a generator back in; version-agnostic helper functions that accept 'any data' and blindly call from_pandas.","solutions":["If the data is a numpy array or dict of arrays, construct directly: pl.DataFrame(data) or pl.from_numpy(arr)","If the data is Arrow (pyarrow.Table / RecordBatch / arrow_c_stream), use pl.from_arrow(data)","If the data is genuinely pandas-like from another library (modin, cudf, duckdb relation .df()), convert to pandas first: pl.from_pandas(data.to_pandas()) or pl.from_pandas(data.df())","Wrap non-iterable scalars in a container: pl.DataFrame({'col': [value]})"],"exampleFix":"# before\npl.from_pandas(np.array([[1, 2], [3, 4]]))\n\n# after\npl.from_numpy(np.array([[1, 2], [3, 4]]))","handlingStrategy":"type-guard","validationCode":"import pandas as pd\n\ndef to_polars_compat(data):\n    if isinstance(data, (pd.DataFrame, pd.Series)):\n        import polars as pl\n        return pl.from_pandas(data)\n    import polars as pl\n    return pl.DataFrame(data)","typeGuard":"import pandas as pd\nfrom typing import TypeGuard\n\ndef is_pandas_frame_or_series(data: object) -> TypeGuard[pd.DataFrame | pd.Series]:\n    return isinstance(data, (pd.DataFrame, pd.Series))","tryCatchPattern":"try:\n    df = pl.from_pandas(data)\nexcept TypeError as e:\n    raise TypeError(f'from_pandas got {type(data).__name__}; wrap or use pl.DataFrame/from_arrow') from e","preventionTips":["Reserve pl.from_pandas exclusively for pandas objects; route numpy through pl.from_numpy and Arrow through pl.from_arrow","In generic ETL helpers, dispatch on isinstance(data, (pd.DataFrame, pd.Series)) before choosing the converter","Log the input type when conversion fails so the misrouted branch is obvious"],"tags":["pandas","type-mismatch","conversion","from-pandas"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}