huggingface/transformers · error · ValueError

You should supply an instance of `transformers.BatchFeature`

Error message

You should supply an instance of `transformers.BatchFeature` or list of `transformers.BatchFeature` to this method that includes {self.model_input_names[0]}, but you provided {list(processed_features.keys())}

What it means

Sequence feature extractors (Wav2Vec2, Whisper feature branch, etc.) pad a batch by reading their primary model input name (usually 'input_values' or 'input_features'). If that key is missing from the processed features, padding cannot proceed and this ValueError is raised, listing the keys actually provided.

Source

Thrown at src/transformers/feature_extraction_sequence_utils.py:129

                [What are attention masks?](../glossary#attention-mask)
            return_tensors (`str` or [`~utils.TensorType`], *optional*):
                If set, will return tensors instead of list of python integers. Acceptable values are:

                - `'pt'`: Return PyTorch `torch.Tensor` objects.
                - `'np'`: Return Numpy `np.ndarray` objects.
        """
        # If we have a list of dicts, let's convert it in a dict of lists
        # We do this to allow using this method as a collate_fn function in PyTorch Dataloader
        if isinstance(processed_features, (list, tuple)) and isinstance(processed_features[0], (dict, BatchFeature)):
            # Call .keys() explicitly for compatibility with TensorDict and other Mapping subclasses
            processed_features = {
                key: [example[key] for example in processed_features] for key in processed_features[0].keys()
            }

        # The model's main input name, usually `input_values`, has be passed for padding
        if self.model_input_names[0] not in processed_features:
            raise ValueError(
                "You should supply an instance of `transformers.BatchFeature` or list of `transformers.BatchFeature`"
                f" to this method that includes {self.model_input_names[0]}, but you provided"
                f" {list(processed_features.keys())}"
            )

        required_input = processed_features[self.model_input_names[0]]
        return_attention_mask = (
            return_attention_mask if return_attention_mask is not None else self.return_attention_mask
        )

        if len(required_input) == 0:
            if return_attention_mask:
                processed_features["attention_mask"] = []
            return processed_features

        # If we have PyTorch tensors or lists as inputs, we cast them as Numpy arrays
        # and rebuild them afterwards if no return_tensors is specified
        # Note that we lose the specific device the tensor may be on for PyTorch

View on GitHub (pinned to a597f97485)

Solutions

1. Pass the output of feature_extractor(...) itself (which always contains the main input) instead of a hand-built dict
2. Check the error message: it names the required key and what you actually provided — add the missing key
3. Inspect feature_extractor.model_input_names[0] to see the exact expected key

Example fix

# before
fe.pad({"attention_mask": mask}, padding=True)

# after
fe.pad({"input_values": raw_audio, "attention_mask": mask}, padding=True)

def validate_for_padding(fe, batch):
    main = fe.model_input_names[0]
    if main not in batch:
        raise KeyError(f"missing {main}; has {list(batch.keys())}")
    return batch

def has_main_input(fe, batch: dict) -> bool:
    return fe.model_input_names[0] in batch

try:
    fe.pad(batch, padding=True)
except ValueError as e:
    if "You should supply" in str(e):
        raise ValueError("rebuild batch via the feature extractor before padding") from e
    raise

When it happens

Trigger: Calling feature_extractor(..., padding=True/padding='longest') on a dict/BatchFeature that lacks the main input key — e.g. passing only 'attention_mask', or a truncated/renamed batch dict.

Common situations: Rebuilding feature dicts manually and dropping the main key; collating partial batches in a DataLoader; passing text-tokenizer-style dicts to an audio feature extractor.

Related errors

• When setting ``padding={PaddingStrategy.MAX_LENGTH}``, make
• type of {first_element} unknown: {type(first_element)}. Shou
• Some items in the output dictionary have a different batch s
• Invalid padding strategy:{padding_side}
• When setting ``truncation=True``, make sure that ``max_lengt

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