pandas-dev/pandas · error · KeyError

Columns not found: {str(bad_keys)[1:-1]}

Error message

Columns not found: {str(bad_keys)[1:-1]}

What it means

Raised by SelectionMixin.__getitem__ when a list/tuple/Series/Index/array key references one or more columns not present in obj.columns. The bad keys are reported by name. Distinguishes list-key lookups from single-key lookups.

Source

Thrown at pandas/core/base.py:219

        if isinstance(self.obj, ABCSeries):
            return self.obj

        if self._selection is not None:
            return self.obj[self._selection_list]

        if len(self.exclusions) > 0:
            return self.obj._drop_axis(self.exclusions, axis=1)
        else:
            return self.obj

    def __getitem__(self, key):
        if self._selection is not None:
            raise IndexError(f"Column(s) {self._selection} already selected")

        if isinstance(key, (list, tuple, ABCSeries, ABCIndex, np.ndarray)):
            if len(self.obj.columns.intersection(key)) != len(set(key)):
                bad_keys = list(set(key).difference(self.obj.columns))
                raise KeyError(f"Columns not found: {str(bad_keys)[1:-1]}")
            return self._gotitem(list(key), ndim=2)

        else:
            if key not in self.obj:
                raise KeyError(f"Column not found: {key}")
            ndim = self.obj[key].ndim
            return self._gotitem(key, ndim=ndim)

    def _gotitem(self, key, ndim: int, subset=None):
        """
        sub-classes to define
        return a sliced object

        Parameters
        ----------
        key : str / list of selections
        ndim : {1, 2}
            requested ndim of result

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Validate the list against obj.columns before selection: `[c for c in cols if c in df.columns]`.
2. Fix upstream renames so expected columns exist.
3. Use errors-tolerant selection or assert the schema at load time.

Example fix

// before
g = df.groupby('g')[['a','mistake']]

// after
cols = ['a','mistake']
present = [c for c in cols if c in df.columns]
g = df.groupby('g')[present]

missing = set(keys) - set(obj.columns)
if missing:
    raise KeyError(f'columns not found: {missing}')

def all_columns_present(df, keys) -> bool:
    return set(keys).issubset(df.columns)

try:
    sub = holder[keys]
except KeyError as e:
    if 'not found' in str(e):
        keys = [k for k in keys if k in holder.obj.columns]
        sub = holder[keys]
    else:
        raise

When it happens

Trigger: `df.groupby('g')[['a','x']]` where 'x' is not a column; selecting missing columns from a groupby/rolling selection mixin holder.

Common situations: Typo in column names; columns renamed/dropped upstream; dynamic column lists sourced from config.

Related errors

• Column not found: {key}
• Column(s) {self._selection} already selected
• numpy operations are not valid with groupby. Use .groupby(..
• The numba engine only supports using string or numeric colum
• Label(s) {list(cols)} do not exist

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