pandas-dev/pandas · error · ValueError

The numba engine only supports using string or numeric colum

Error message

The numba engine only supports using string or numeric column names

What it means

Raised by set_numba_data in the numba engine extension layer. When engine='numba' is used for DataFrame.apply/transform or rolling/groupby apply, pandas exposes the index and columns to numba; if their underlying data has object/string dtype that is NOT a pure string array (e.g. mixed Python objects), it cannot be lowered to a numba-compatible string array, so the run is aborted.

Source

Thrown at pandas/core/_numba/extensions.py:56

from pandas.core.indexes.base import Index
from pandas.core.indexing import _iLocIndexer
from pandas.core.internals import SingleBlockManager
from pandas.core.series import Series


# Helper function to hack around fact that Index casts numpy string dtype to object
#
# Idea is to set an attribute on an Index called _numba_data
# that is the original data, or the object data casted to numpy string dtype,
# with a context manager that is unset afterwards
@contextmanager
def set_numba_data(index: Index):
    numba_data = index._data
    if numba_data.dtype in (object, "string"):
        numba_data = np.asarray(numba_data)
        if not lib.is_string_array(numba_data):
            raise ValueError(
                "The numba engine only supports using string or numeric column names"
            )
        numba_data = numba_data.astype("U")
    try:
        index._numba_data = numba_data
        yield index
    finally:
        del index._numba_data


# TODO: Range index support
# (this currently lowers OK, but does not round-trip)
class IndexType(types.Type):
    """
    The type class for Index objects.
    """

    def __init__(self, dtype, layout, pyclass: any) -> None:

View on GitHub (pinned to 71959b8cb9)

Solutions

Fall back to engine='python' (the default) when index/columns contain non-string, non-numeric objects.
Normalize the offending axis: cast columns/index to all strings (df.columns = df.columns.astype(str)) or to a clean numeric dtype before the numba call.
Build a fresh integer/string-only Index for the operation.

Example fix

# before
df.apply(my_func, engine='numba')  # columns are mixed object
# after
df.columns = df.columns.astype(str)
df.apply(my_func, engine='numba')

Defensive patterns

Strategy: validation

Validate before calling

def numba_ready_axes(df):
    for axis in (df.index, df.columns):
        vals = np.asarray(axis._data if hasattr(axis, '_data') else axis)
        if vals.dtype == object and not all(isinstance(x, (str, int, float)) for x in vals):
            return False
    return True

if not numba_ready_axes(df):
    df.columns = df.columns.astype(str)

Type guard

def has_clean_string_or_numeric(arr) -> bool:
    import numpy as np
    from pandas.core import lib
    a = np.asarray(arr)
    if a.dtype not in (object, 'string', 'U'):
        return a.dtype.kind in 'iufcb'
    return lib.is_string_array(a)

Try / catch

try:
    out = df.apply(func, engine='numba')
except ValueError:
    out = df.apply(func, engine='python')

Prevention

Keep DataFrame columns/index as numeric or pure-string dtypes when using engine='numba'.
Validate axes before the numba call, fall back to python engine otherwise.
Avoid mixing object types in group keys for numba-backed groupby/rolling.

When it happens

Trigger: df.apply(func, engine='numba', ...) or df.transform(func, engine='numba') where df.columns or df.index is object dtype holding non-string values; groupby/rolling .apply(..., engine='numba') with group keys that are mixed-type objects.

Common situations: Switching an apply call to engine='numba' on a DataFrame whose columns are integers and strings mixed, or whose index was constructed from a list of mixed Python objects; upgrading code that previously relied on the python engine which tolerated object dtypes.

Related errors

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