huggingface/transformers · error · ValueError

When setting ``truncation=True``, make sure that ``max_lengt

Error message

When setting ``truncation=True``, make sure that ``max_length`` is defined.

What it means

The internal _truncate step only cuts sequences when both truncation=True and a max_length to cut to are known. truncation=True without max_length leaves no defined target length, so the extractor refuses rather than truncating to an arbitrary length.

Source

Thrown at src/transformers/feature_extraction_sequence_utils.py:322

        Truncate inputs to predefined length or max length in the batch

        Args:
            processed_features(`Union[dict[str, np.ndarray], BatchFeature]`):
                Dictionary of input values (`np.ndarray[float]`) / input vectors (`list[np.ndarray[float]]`) or batch
                of inputs values (`list[np.ndarray[int]]`) / input vectors (`list[np.ndarray[int]]`)
            max_length (`int`, *optional*):
                maximum length of the returned list and optionally padding length (see below)
            pad_to_multiple_of (`int`, *optional*) :
                Integer if set will pad the sequence to a multiple of the provided value. This is especially useful to
                enable the use of Tensor Core on NVIDIA hardware with compute capability `>= 7.5` (Volta), or on TPUs
                which benefit from having sequence lengths be a multiple of 128.
            truncation (`bool`, *optional*):
                Activates truncation to cut input sequences longer than `max_length` to `max_length`.
        """
        if not truncation:
            return processed_features
        elif truncation and max_length is None:
            raise ValueError("When setting ``truncation=True``, make sure that ``max_length`` is defined.")

        required_input = processed_features[self.model_input_names[0]]

        # find `max_length` that fits `pad_to_multiple_of`
        if max_length is not None and pad_to_multiple_of is not None and (max_length % pad_to_multiple_of != 0):
            max_length = ((max_length // pad_to_multiple_of) + 1) * pad_to_multiple_of

        needs_to_be_truncated = len(required_input) > max_length

        if needs_to_be_truncated:
            processed_features[self.model_input_names[0]] = processed_features[self.model_input_names[0]][:max_length]
            if "attention_mask" in processed_features:
                processed_features["attention_mask"] = processed_features["attention_mask"][:max_length]

        return processed_features

    def _get_padding_strategies(self, padding=False, max_length=None):
        """

View on GitHub (pinned to a597f97485)

Solutions

Pass max_length together with truncation: fe(audio, truncation=True, max_length=16000)
Or define max_length once on the extractor (fe.max_length = N) if the subclass supports it
Drop truncation=True if you want full-length features

Example fix

# before
fe(audio, truncation=True)

# after
fe(audio, truncation=True, max_length=160000)

Defensive patterns

Strategy: validation

Validate before calling

def truncate_kwargs(truncation, max_length):
    if truncation and max_length is None:
        raise ValueError("truncation requires max_length")
    return {"truncation": truncation, "max_length": max_length}

Try / catch

try:
    fe(audio, truncation=True)
except ValueError as e:
    if "max_length" in str(e):
        fe(audio, truncation=True, max_length=default_len)
    else:
        raise

Prevention

Always pair truncation=True with an explicit max_length
Do not assume tokenizer defaults transfer to feature extractors
Centralize length constants in one config object

When it happens

Trigger: Calling __call__ or _truncate with truncation=True but max_length=None and no model_max_length fallback at this layer: fe(audio, truncation=True) with no max_length argument.

Common situations: Porting tokenizer-style calls (where max_length defaults from model config) to feature extractors, which have no such default; setting truncation globally in a processing config but forgetting the length.

Related errors

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