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. ExtensionArray.fillna only supports scalar or array-like values; dict-based per-position filling is a Series-level feature (Series.fillna maps dict keys to labels). pandas raises TypeError pointing the user to Series.fillna rather than silently mishandling the dict.

Source

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

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

Solutions

Use Series.fillna for dict-based fills: pd.Series(arr).fillna({0:1, 2:3}).
Pass a scalar to the array: arr.fillna(0).
Pass an array-like of fill values aligned by position: arr.fillna(np.array([...])).
Convert positional dict to a list: arr.fillna([v for _,v in sorted(d.items())]).

Example fix

# before
arr = pd.array([1, None, 3], dtype='int64[pyarrow]')
arr.fillna({1: 99})  # TypeError
# after - use Series for dict semantics
filled = pd.Series(arr).fillna({1: 99}).array
# or scalar/array
filled = arr.fillna(99)

Defensive patterns

Strategy: type-guard

Validate before calling

def fillna_arrow(arr, value):
    import collections
    if isinstance(value, dict):
        # use Series for dict semantics
        import pandas as pd
        return pd.Series(arr).fillna(value).array
    return arr.fillna(value)

filled = fillna_arrow(arr, {1: 99})

Type guard

import collections.abc

def is_fillna_dict(value) -> bool:
    return isinstance(value, collections.abc.Mapping)

Try / catch

try:
    out = arr.fillna(value)
except TypeError as e:
    if 'does not support filling with a dict' in str(e):
        import pandas as pd
        out = pd.Series(arr).fillna(value).array
    else:
        raise

Prevention

Use Series.fillna (not ExtensionArray.fillna) for dict-based fills.
Pass scalars or array-likes to ExtensionArray.fillna.
Gate dict handling at the API boundary before reaching the array.

When it happens

Trigger: `arrow_arr.fillna({0: 1, 2: 3})`, `pd.array([...], dtype='int64[pyarrow]').fillna({'col': 0})`. Calling .fillna on the raw extension array (arr.fillna) rather than on a Series.

Common situations: Working at the array level (.array / pd.array(...)) and passing a dict that worked on Series.fillna; generic pipelines that always pass dicts to fillna regardless of object type.

Related errors

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