pandas-dev/pandas · error · TypeError

ExtensionArray.fillna does not support filling with a dict…

Error message

ExtensionArray.fillna does not support filling with a dict. Use Series.fillna instead.

What it means

Raised by ArrowExtensionArray.fillna when `value` is a dict. The extension-array-level fillna only supports scalar and array-like values; dict-based per-index filling is a Series/DataFrame concern because it requires label alignment. Users are redirected to Series.fillna.

Solutions

Use Series.fillna(dict) or DataFrame.fillna(dict) instead of operating on the raw array.
If you must use the array, expand the dict to an array-like of the same length aligned to positions.
Build a position-aligned fill array from the dict: np.array([d.get(i, default) for i in range(len(arr))]).

Example fix

# before
arr = pd.array([1, None, 3], dtype="int64[pyarrow]")
arr.fillna({1: 99})  # raises TypeError

# after
pd.Series(arr).fillna({1: 99}).array

Defensive patterns

Strategy: type-guard

Validate before calling

def safe_fillna(arr, value, **kw):
    if isinstance(value, dict):
        raise TypeError('Use Series.fillna(dict) instead of array.fillna(dict)')
    return arr.fillna(value, **kw)

Type guard

def is_dict_value(v) -> bool:
    return isinstance(v, dict)

Prevention

Call Series.fillna(dict) instead of operating on the raw extension array.
Expand dicts to position-aligned arrays before array-level fillna.
Keep dict-based filling at the Series/DataFrame layer.

When it happens

Trigger: arr.fillna({0: 10, 1: 20}) on an ArrowExtensionArray; calling .fillna on the underlying array of a Series with a dict (rare, since Series.fillna usually intercepts); custom code that pulls the .array property and calls fillna(dict).

Common situations: Users who learned the dict syntax from Series.fillna and try it on the raw extension array; tutorials showing dict-based filling applied at the wrong layer; converting code from object dtype to pyarrow without adjusting the fill call.

Related errors

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

Appendix: source

Thrown at pandas/core/arrays/arrow/array.py:1719

            NA values.
        api.extensions.ExtensionArray.isna : A 1-D array indicating if
            each value is missing.

        Examples
        --------
        >>> arr = pd.array(
        ...     [np.nan, np.nan, 2, 3, np.nan, np.nan], dtype="int64[pyarrow]"
        ... )
        >>> arr.fillna(0)
        <ArrowExtensionArray>
        [0, 0, 2, 3, 0, 0]
        Length: 6, dtype: int64[pyarrow]
        """
        if not self._hasna:
            return self.copy()

        if isinstance(value, dict):
            raise TypeError(
                "ExtensionArray.fillna does not support filling with a dict. "
                "Use Series.fillna instead."
            )

        if limit is not None:
            return super().fillna(value=value, limit=limit, copy=copy)

        if isinstance(value, (np.ndarray, ExtensionArray)):
            # Similar to check_value_size, but we do not mask here since we may
            #  end up passing it to the super() method.
            if len(value) != len(self):
                raise ValueError(
                    f"Length of 'value' does not match. Got ({len(value)}) "
                    f" expected {len(self)}"
                )

        try:
            fill_value = self._box_pa(value, pa_type=self._pa_array.type)

View on GitHub (pinned to 3b7651241d)