pandas-dev/pandas · error · AttributeError

Can only use the '.list' accessor with 'list[pyarrow]'…

Error message

Can only use the '.list' accessor with 'list[pyarrow]' dtype, not {dtype}.

What it means

`AttributeError` from `ArrowAccessor._validate` for the `.list` accessor. It fires when the Series dtype is not an `ArrowDtype` over a pyarrow list type (list / fixed_size_list / large_list). pandas deliberately raises `AttributeError` (not `TypeError`) so that `inspect`/dir()/autocomplete and `hasattr(s, 'list')` behave naturally on non-list Series — the accessor simply appears absent.

Solutions

1. Construct the Series with an explicit Arrow list dtype: `pd.Series(data, dtype=pd.ArrowDtype(pa.list_(pa.int64())))`.
2. Convert an existing Series: `s = s.astype(pd.ArrowDtype(pa.list_(pa.int64())))` before using `.list`.
3. Guard with `if isinstance(s.dtype, pd.ArrowDtype) and pa.types.is_list(s.dtype.pyarrow_dtype): ...`.

Example fix

// before
s = pd.Series([[1,2],[3]])
s.list.len()   # object dtype -> AttributeError

// after
import pyarrow as pa
s = pd.Series([[1,2],[3]], dtype=pd.ArrowDtype(pa.list_(pa.int64())))
s.list.len()

import pyarrow as pa
from pandas.core.dtypes.dtypes import ArrowDtype
if not (isinstance(s.dtype, ArrowDtype) and pa.types.is_list(s.dtype.pyarrow_dtype)):
    s = s.astype(pd.ArrowDtype(pa.list_(pa.int64())))
s.list.len()

def is_arrow_list_series(s) -> bool:
    import pyarrow as pa
    from pandas.core.dtypes.dtypes import ArrowDtype
    return (isinstance(s.dtype, ArrowDtype)
            and (pa.types.is_list(s.dtype.pyarrow_dtype)
                 or pa.types.is_large_list(s.dtype.pyarrow_dtype)
                 or pa.types.is_fixed_size_list(s.dtype.pyarrow_dtype)))

try:
    out = s.list.len()
except AttributeError as e:
    if '.list' in str(e):
        s = s.astype(pd.ArrowDtype(pa.list_(pa.int64())))
        out = s.list.len()
    else:
        raise

When it happens

Trigger: `s.list` where `s.dtype` is object, `string`, numpy list-of-lists, an `ArrowDtype` that is not a list type (e.g. `int64[pyarrow]`, `string[pyarrow]`), or a `large_list`/`fixed_size_list` is fine but a struct/decimal is not.

Common situations: Calling `.list.flatten()` / `.list.len()` on a Series that was not constructed with `pd.ArrowDtype(pa.list_(...))`; dtype silently downcast to object by a previous op; user assumes pyarrow storage but the Series is plain object dtype.

Related errors

• Can only use the '.struct' accessor with 'struct[pyarrow]'…
• key must be an int or slice, got
• ' ' object is not iterable
• name_or_index must be an int, str, bytes…
• to_concat must have the same dtype

AI-assisted analysis of pandas-dev/pandas@3b7651241d (2026-08-11). Data as JSON: /api/errors/f908adbff5b9a2f2. Report an issue: GitHub.

Appendix: source

Thrown at pandas/core/arrays/arrow/accessors.py:48

    )


class ArrowAccessor(metaclass=ABCMeta):
    @abstractmethod
    def __init__(self, data, validation_msg: str) -> None:
        self._data = data
        self._validation_msg = validation_msg
        self._validate(data)

    @abstractmethod
    def _is_valid_pyarrow_dtype(self, pyarrow_dtype) -> bool:
        pass

    def _validate(self, data) -> None:
        dtype = data.dtype
        if not HAS_PYARROW or not isinstance(dtype, ArrowDtype):
            # Raise AttributeError so that inspect can handle non-struct Series.
            raise AttributeError(self._validation_msg.format(dtype=dtype))

        if not self._is_valid_pyarrow_dtype(dtype.pyarrow_dtype):
            # Raise AttributeError so that inspect can handle invalid Series.
            raise AttributeError(self._validation_msg.format(dtype=dtype))

    @property
    def _pa_array(self):
        return self._data.array._pa_array


class ListAccessor(ArrowAccessor):
    """
    Accessor object for list data properties of the Series values.

    Parameters
    ----------
    data : Series
        Series containing Arrow list data.

View on GitHub (pinned to 3b7651241d)