{"record":{"id":"b0a9ea1865a7a216","repo":"pandas-dev/pandas","slug":"the-numba-engine-only-supports-using-string-or-num","errorCode":null,"errorMessage":"The numba engine only supports using string or numeric column names","messagePattern":"The numba engine only supports using string or numeric column names","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/_numba/extensions.py","lineNumber":56,"sourceCode":"\nfrom pandas.core.indexes.base import Index\nfrom pandas.core.indexing import _iLocIndexer\nfrom pandas.core.internals import SingleBlockManager\nfrom pandas.core.series import Series\n\n\n# Helper function to hack around fact that Index casts numpy string dtype to object\n#\n# Idea is to set an attribute on an Index called _numba_data\n# that is the original data, or the object data casted to numpy string dtype,\n# with a context manager that is unset afterwards\n@contextmanager\ndef set_numba_data(index: Index):\n    numba_data = index._data\n    if numba_data.dtype in (object, \"string\"):\n        numba_data = np.asarray(numba_data)\n        if not lib.is_string_array(numba_data):\n            raise ValueError(\n                \"The numba engine only supports using string or numeric column names\"\n            )\n        numba_data = numba_data.astype(\"U\")\n    try:\n        index._numba_data = numba_data\n        yield index\n    finally:\n        del index._numba_data\n\n\n# TODO: Range index support\n# (this currently lowers OK, but does not round-trip)\nclass IndexType(types.Type):\n    \"\"\"\n    The type class for Index objects.\n    \"\"\"\n\n    def __init__(self, dtype, layout, pyclass: any) -> None:","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/core/_numba/extensions.py#L38-L74","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\ndf.apply(my_func, engine='numba')  # columns are mixed object\n# after\ndf.columns = df.columns.astype(str)\ndf.apply(my_func, engine='numba')","handlingStrategy":"validation","validationCode":"def numba_ready_axes(df):\n    for axis in (df.index, df.columns):\n        vals = np.asarray(axis._data if hasattr(axis, '_data') else axis)\n        if vals.dtype == object and not all(isinstance(x, (str, int, float)) for x in vals):\n            return False\n    return True\n\nif not numba_ready_axes(df):\n    df.columns = df.columns.astype(str)","typeGuard":"def has_clean_string_or_numeric(arr) -> bool:\n    import numpy as np\n    from pandas.core import lib\n    a = np.asarray(arr)\n    if a.dtype not in (object, 'string', 'U'):\n        return a.dtype.kind in 'iufcb'\n    return lib.is_string_array(a)","tryCatchPattern":"try:\n    out = df.apply(func, engine='numba')\nexcept ValueError:\n    out = df.apply(func, engine='python')","preventionTips":["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."],"tags":["numba","engine","dtype","columns","apply"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}