{"record":{"id":"b85a6bd6e44b84c6","repo":"pandas-dev/pandas","slug":"name-or-index-must-be-an-int-str-bytes-pyarrow","errorCode":null,"errorMessage":"name_or_index must be an int, str, bytes, pyarrow.compute.Expression, or list of those","messagePattern":"name_or_index must be an int, str, bytes, pyarrow\\.compute\\.Expression, or list of those","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/arrow/accessors.py","lineNumber":463,"sourceCode":"                name = level_name_or_index\n            elif isinstance(level_name_or_index, pc.Expression):\n                name = str(level_name_or_index)\n            elif is_list_like(level_name_or_index):\n                # For nested input like [2, 1, 2]\n                # iteratively get the struct and field name. The last\n                # one is used for the name of the index.\n                level_name_or_index = list(reversed(level_name_or_index))\n                selected = data\n                while level_name_or_index:\n                    # we need the cast, otherwise mypy complains about\n                    # getting ints, bytes, or str here, which isn't possible.\n                    level_name_or_index = cast(\"list\", level_name_or_index)\n                    name_or_index = level_name_or_index.pop()\n                    name = get_name(name_or_index, selected)\n                    selected = selected.type.field(selected.type.get_field_index(name))\n                    name = selected.name\n            else:\n                raise ValueError(\n                    \"name_or_index must be an int, str, bytes, \"\n                    \"pyarrow.compute.Expression, or list of those\"\n                )\n            return name\n\n        pa_arr = self._data.array._pa_array\n        name = get_name(name_or_index, pa_arr)\n        field_arr = pc.struct_field(pa_arr, name_or_index)\n\n        return Series(\n            field_arr,\n            dtype=ArrowDtype(field_arr.type),\n            index=self._data.index,\n            name=name,\n        )\n\n    def explode(self) -> DataFrame:\n        \"\"\"","sourceCodeStart":445,"sourceCodeEnd":481,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/arrow/accessors.py#L445-L481","documentation":"`ValueError('name_or_index must be an int, str, bytes, pyarrow.compute.Expression, or list of those')` from the inner `get_name` of `StructAccessor.field`. The accepted shapes are: int field index, str/bytes field name, a `pyarrow.compute.Expression` (e.g. `pc.field('x')`), or a list of those for nested struct traversal. Any other type (dict, tuple, numpy scalar, None) lands in the `else`.","triggerScenarios":"`s.struct.field({'a': 1})`, `s.struct.field(None)`, `s.struct.field((0,1))` (tuple instead of list — note only `is_list_like` is allowed, which does include tuples... actually `is_list_like` returns True for tuples, so the real trigger is non-list-like types: scalars of wrong dtype, dict, None, custom objects).","commonSituations":"Passing a dict (mistaking the API for a constructor); passing None; passing a numpy array of names; passing a custom object whose type is neither str/bytes/int/Expression nor list-like.","solutions":["Pass a field name: `s.struct.field('a')`.","Pass a positional int: `s.struct.field(0)`.","For nested access use a list of those: `s.struct.field(['version', 'minor'])`.","For Expression form use `pyarrow.compute.field('a')`."],"exampleFix":"// before\ns.struct.field({'name': 'a'})   # dict -> ValueError\ns.struct.field(None)            # -> ValueError\n\n// after\ns.struct.field('a')\ns.struct.field(['version', 'minor'])","handlingStrategy":"type-guard","validationCode":"import pyarrow.compute as pc\nfrom pandas.api.types import is_list_like\nif not isinstance(name_or_index, (int, str, bytes, pc.Expression)) and not is_list_like(name_or_index):\n    raise TypeError('name_or_index must be int, str, bytes, pc.Expression, or list of those')\ns.struct.field(name_or_index)","typeGuard":"def is_valid_struct_field_key(key) -> bool:\n    import pyarrow.compute as pc\n    from pandas.api.types import is_list_like\n    return isinstance(key, (int, str, bytes, pc.Expression)) or is_list_like(key)","tryCatchPattern":"try:\n    out = s.struct.field(name_or_index)\nexcept ValueError as e:\n    if 'name_or_index must be' in str(e):\n        raise TypeError('Pass a field name (str), index (int), or list for nested access') from e\n    raise","preventionTips":["Use str field names or int indices; lists for nested traversal","Do not pass dicts, None, or custom objects"],"tags":["accessor","struct","field","pyarrow","argument-validation"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}