pandas-dev/pandas · error · ValueError

Column ' ' not found in given DataFrame. Hint: did you mean…

Error message

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

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

What it means

Raised inside the closure returned by pd.col() when the Expression is evaluated against a DataFrame whose columns do not contain col_name. Evaluation is deferred, so this fires at the point of use (e.g. when df.assign or df.loc materializes the expression), not at pd.col() call time. The message includes a hint listing the DataFrame's columns (truncated to 90 chars) to suggest the intended name.

Solutions

1. Confirm col_name in df.columns at the point the Expression is consumed.
2. Build the Expression after schema fixes (rename/strip) are applied.
3. Use the hint in the error to pick the correct column name.

Example fix

// before
df = df.assign(total=pd.col('prize'))
// after
assert 'price' in df.columns, df.columns.tolist()
df = df.assign(total=pd.col('price'))

if col_name not in df.columns:
    raise ValueError(f'{col_name} not in {df.columns.tolist()}')
expr = pd.col(col_name)
df.assign(new=expr)

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

When it happens

Trigger: df.assign(new=pd.col('misspelled')); df.loc[pd.col('absent') > 0]; any consumer of Expression whose DataFrame lacks the column. Triggered when _eval_expression runs the inner func.

Common situations: Renaming/dropping columns after building an Expression; using pd.col against a DataFrame of a different schema; case/whitespace mismatches in column names.

Related errors

• boolean value of an expression is ambiguous
• Expression objects are not copiable
• Expression objects are not iterable
• abs(axis) must be less than ndim
• can only convert an array of size 1 to a Python scalar

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

Appendix: 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 3b7651241d)