pandas-dev/pandas · error · ValueError

Column '{col_name}' not found in given DataFrame. Hint: did

Error message

Column '{col_name}' not found in given DataFrame.

Hint: did you mean one of {columns_str} instead?

What it means

Raised at evaluation time inside the closure created by pandas.col (pandas/core/col.py:426) when the deferred Expression is evaluated against a DataFrame whose columns do not contain `col_name`. Because evaluation is deferred, the failure surfaces only when assign/loc/pipe actually invokes the Expression against a frame, and the message lists the DataFrame's actual columns as a hint.

Source

Thrown at pandas/core/col.py:426

          name  speed
    1  narwhal    110
    """
    if not isinstance(col_name, Hashable):
        msg = f"Expected Hashable, got: {type(col_name)}"
        raise TypeError(msg)

    def func(df: DataFrame) -> Series:
        if col_name not in df.columns:
            columns_str = str(df.columns.tolist())
            max_len = 90
            if len(columns_str) > max_len:
                columns_str = columns_str[:max_len] + "...]"

            msg = (
                f"Column '{col_name}' not found in given DataFrame.\n\n"
                f"Hint: did you mean one of {columns_str} instead?"
            )
            raise ValueError(msg)
        return df[col_name]

    return Expression(func, f"col({col_name!r})")


__all__ = ["Expression", "col"]

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Inspect `df.columns.tolist()` and correct the name passed to pd.col.
2. If the Expression is reused across frames, guard with `if col_name in df.columns` before building it, or branch on schema.
3. Normalize column names up front (df.rename, str.strip, str.lower) so the Expression name matches.

Example fix

# before
df.assign(v2=pd.col('spead') * 2)  # typo

# after
df.assign(v2=pd.col('speed') * 2)

import pandas as pd

def col_if_exists(df, name):
    if name not in df.columns:
        raise KeyError(f"'{name}' not in {list(df.columns)}")
    return pd.col(name)

def column_exists(df, name) -> bool:
    return name in df.columns

try:
    df = df.assign(new=pd.col(name) * 2)
except ValueError as e:
    if 'not found' in str(e):
        import difflib
        cols = list(df.columns)
        match = difflib.get_close_matches(name, cols, n=1)
        name = match[0] if match else name
        df = df.assign(new=pd.col(name) * 2)
    else:
        raise

When it happens

Trigger: `df.assign(new=pd.col('missing'))`, `df.loc[pd.col('missing') > 5]`, or any pd.col-derived Expression evaluated against a DataFrame lacking that column. Also when a reusable Expression is applied to multiple frames of differing schema.

Common situations: Typos in column names, case sensitivity ("Name" vs "name"), whitespace differences, applying a pipeline built for one dataset to another with renamed columns, or stale Expressions after a refactor.

Related errors

• boolean value of an expression is ambiguous
• Expression objects are not iterable
• Expression objects are not copiable
• Expected Hashable, got: {type(col_name)}
• Value must be an instance of {type_repr}

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