huggingface/transformers · error · KeyError

Indexing with integers is not available when using Python ba

Error message

Indexing with integers is not available when using Python based feature extractors

What it means

BatchFeature is a dict-like container; its __getitem__ only accepts string keys ('input_values', 'attention_mask', ...). Integer/positional indexing has no meaning for a mapping of named features, so it raises KeyError with this explanatory message.

Source

Thrown at src/transformers/feature_extraction_utils.py:93

    def __init__(
        self,
        data: dict[str, Any] | None = None,
        tensor_type: None | str | TensorType = None,
        skip_tensor_conversion: list[str] | set[str] | None = None,
    ):
        super().__init__(data)
        self.skip_tensor_conversion = skip_tensor_conversion
        self.convert_to_tensors(tensor_type=tensor_type)

    def __getitem__(self, item: str) -> Any:
        """
        If the key is a string, returns the value of the dict associated to `key` ('input_values', 'attention_mask',
        etc.).
        """
        if isinstance(item, str):
            return self.data[item]
        else:
            raise KeyError("Indexing with integers is not available when using Python based feature extractors")

    def __getattr__(self, item: str):
        try:
            return self.data[item]
        except KeyError:
            raise AttributeError

    def __getstate__(self):
        return {"data": self.data}

    def __setstate__(self, state):
        if "data" in state:
            self.data = state["data"]

    def _get_is_as_tensor_fns(self, tensor_type: str | TensorType | None = None):
        if tensor_type is None:
            return None, None

View on GitHub (pinned to a597f97485)

Solutions

Access features by name: batch['input_values'], batch['attention_mask']
If you wanted tensor-style behavior, call the extractor with return_tensors='pt' and index the tensor
To take a slice of the batch, slice each value: {k: v[:2] for k, v in batch.items()}

Example fix

# before
first = batch[0]

# after
first = {k: v[:1] for k, v in batch.items()}

Defensive patterns

Strategy: type-guard

Validate before calling

def get_item(batch, key):
    if not isinstance(key, str):
        raise KeyError("BatchFeature supports string keys only")
    return batch[key]

Type guard

from transformers import BatchFeature

def is_batch_feature(x) -> bool:
    return isinstance(x, BatchFeature)

Try / catch

try:
    value = batch[0]
except KeyError as e:
    if "Indexing with integers" in str(e):
        value = list(batch.data.values())[0]
    else:
        raise

Prevention

Treat BatchFeature as a dict: access by feature name
Use return_tensors='pt' when tensor-style indexing is needed
Slice batches with dict comprehensions, not positional indexing

When it happens

Trigger: Doing batch[0] or batch[:2] on the object returned by a feature extractor — treating it like a tensor or dataset row instead of a dict.

Common situations: Code written for tensor outputs (return_tensors='pt' absent) that indexes positionally; generic downstream code that tries sequence-style access on any container; iterating incorrectly.

Related errors

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/885d9ea7141aa134. Report an issue: GitHub.