pandas-dev/pandas · error · NumExprClobberingError

Variables in expression

Error message

Variables in expression "{expr}" overlap with builtins: ({s})

What it means

Raised by _check_ne_builtin_clash (called from the numexpr engine path of DataFrame.eval/query) when a column name in the expression collides with a numexpr builtin name (the union of MATHOPS and REDUCTIONS, e.g. sum, min, max, log, exp, sin). The check is a footgun guard: numexpr would otherwise silently treat `sum` as the reduction instead of the column, returning a scalar instead of per-row values. NumExprClobberingError is a ValueError subclass.

Solutions

1. Rename the column: df = df.rename(columns={'sum': 'total'}).
2. Reference it via @ local: total = df['sum']; df.eval('total + 1').
3. Force the python engine: df.eval('sum + 1', engine='python').
4. Quote with backticks (pandas supports `sum` in eval for non-identifier names but it does not bypass this builtin check — rename is the safe option).

Example fix

// before
df.eval('sum + 1')
// after
df = df.rename(columns={'sum': 'total'})
df.eval('total + 1')

import pandas.core.computation.expr as _expr
reserved = set(_expr.MATHOPS) | set(_expr.REDUCTIONS)
clash = set(df.columns) & reserved
if clash:
    raise ValueError(f'rename columns clashing with numexpr builtins: {clash}')

try:
    result = df.eval(expr, engine='numexpr')
except NumExprClobberingError:
    result = df.eval(expr, engine='python')

When it happens

Trigger: df.eval('sum + 1') where 'sum' is a column; df.query('min > 5'); df.eval('log > 0') with a column named 'log'. Only triggers with engine='numexpr' (default when numexpr is installed); the python engine does not raise.

Common situations: Domain columns named after math/reduction functions (common in finance/logs, statistics with 'min'/'max'); legacy datasets; reserved-word column names from CSVs.

Related errors

• cannot evaluate scalar only bool ops
• Function " " does not support keyword arguments
• Invalid engine ' ' passed, valid engines are
• Invalid function call
• keyword error in function call

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

Appendix: source

Thrown at pandas/core/computation/engines.py:43

_ne_builtins = frozenset(MATHOPS + REDUCTIONS)


def _check_ne_builtin_clash(expr: Expr) -> None:
    """
    Attempt to prevent foot-shooting in a helpful way.

    Parameters
    ----------
    expr : Expr
        Terms can contain
    """
    names = expr.names
    overlap = names & _ne_builtins

    if overlap:
        s = ", ".join([repr(x) for x in overlap])
        raise NumExprClobberingError(
            f'Variables in expression "{expr}" overlap with builtins: ({s})'
        )


class AbstractEngine(metaclass=abc.ABCMeta):
    """Object serving as a base class for all engines."""

    has_neg_frac = False

    def __init__(self, expr) -> None:
        self.expr = expr
        self.aligned_axes = None
        self.result_type = None
        self.result_name = None

    def convert(self) -> str:
        """
        Convert an expression for evaluation.

View on GitHub (pinned to 3b7651241d)