pandas-dev/pandas · error · AttributeError

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

Error message

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

What it means

The .list accessor only works on Series of dtype list[pyarrow] (including large_list and fixed_size_list). Line 48 raises AttributeError specifically when the dtype is not even an ArrowDtype (e.g. object, int64, pandas string) or pyarrow is not installed. AttributeError (not ValueError) is used so that hasattr/inspect treat the accessor as absent on non-list Series.

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 71959b8cb9)

Solutions

1. Convert the column to list[pyarrow]: pd.Series(s, dtype=pd.ArrowDtype(pa.list_(pa.int64()))).
2. For object-dtype list columns, use s.apply(len) / s.explode() instead of the .list accessor.

Example fix

// before
s.list.len()  # s.dtype == object
// after
import pyarrow as pa
s = s.astype(pd.ArrowDtype(pa.list_(pa.int64())))
s.list.len()

def to_list_pa(s, value_type=pa.int64()):
    from pandas.core.dtypes.dtypes import ArrowDtype
    if not (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)
    )):
        s = pd.Series(list(s), dtype=ArrowDtype(pa.list_(value_type)))
    return s

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

When it happens

Trigger: s.list.len() (or any s.list method) on a Series of Python lists stored as object dtype, or on int64 / pandas string / float dtype.

Common situations: Forgetting to convert an object-dtype list column to list[pyarrow] before using .list; reading JSON/nested data without specifying the arrow dtype.

Related errors

• Can only use the '.struct' accessor with 'struct[pyarrow]' d
• key must be an int or slice, got {type(key).__name__}
• '{type(self).__name__}' object is not iterable
• operation '{name}' not supported for dtype '{self.dtype}'
• Expected array of {self} type, got {array.type} instead

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