huggingface/transformers · error · ValueError

{self.class.name} only supports {supported_modes}, b

Error message

{self.__class__.__name__} only supports {supported_modes}, but got generation mode '{generation_mode}'.

What it means

Some model classes declare `_supported_generation_modes`, a whitelist of the decoding strategies their implementation can handle (e.g. only GREEDY_SEARCH and SAMPLE). Before decoding, `generate` validates the resolved generation mode against this list and raises when the parameterization you chose resolves to an unsupported mode.

Source

Thrown at src/transformers/generation/utils.py:1562

        # 7. Define which indices contributed to scores
        cut_idx = sequences.shape[-1] - max_beam_length
        indices = sequences[:, cut_idx:] + beam_sequence_indices

        # 8. Compute scores
        transition_scores = stacked_scores.gather(0, indices)

        # 9. Mask out transition_scores of beams that stopped early
        transition_scores[beam_indices_mask] = 0

        return transition_scores

    def _validate_generation_mode(
        self: "GenerativePreTrainedModel", generation_mode, generation_config, generation_mode_kwargs
    ):
        supported_modes = getattr(self, "_supported_generation_modes", None)
        if supported_modes is not None and generation_mode not in supported_modes:
            raise ValueError(
                f"{self.__class__.__name__} only supports {supported_modes}, but got "
                f"generation mode '{generation_mode}'."
            )

        if generation_mode == GenerationMode.BEAM_SEARCH and "streamer" in generation_mode_kwargs:
            raise ValueError(
                "`streamer` cannot be used with beam search (yet!). Make sure that `num_beams` is set to 1."
            )

        if generation_mode == GenerationMode.ASSISTED_GENERATION:
            if generation_config.num_return_sequences > 1:
                raise ValueError(
                    "num_return_sequences has to be 1 when doing assisted generate, "
                    f"but is {generation_config.num_return_sequences}."
                )
            if self._is_stateful:
                # In assisted generation we need the ability to confirm whether the model would pick certain tokens,
                # which is not possible with stateful models (they can't reset to a previous subset of generated text)

View on GitHub (pinned to a597f97485)

Solutions

Read the error message: it lists the exact supported modes; switch parameters to one of them (e.g. keep `num_beams=1`, use `do_sample=True/False`).
Check the class attribute `type(model)._supported_generation_modes` (or inspect the model's docs) to see what is allowed.
If you need the unsupported mode, use a different model class that supports it (e.g. a standard causal LM).
If you maintain a custom model, extend `_supported_generation_modes` only after implementing/verifying that mode's requirements (cache handling, beam reordering, etc.).

Example fix

# before
out = model.generate(**inputs, num_beams=4)  # ValueError: only supports (GREEDY_SEARCH, SAMPLE)

# after
out = model.generate(**inputs, do_sample=True, temperature=0.7, num_beams=1)

Defensive patterns

Strategy: validation

Validate before calling

supported = getattr(type(model), "_supported_generation_modes", None)
if supported is not None:
    # validate after resolving mode, e.g. beam params only if BEAM_SEARCH in supported
    if kwargs.get("num_beams", 1) > 1 and not any("BEAM" in m.name for m in supported):
        kwargs["num_beams"] = 1

Try / catch

try:
    out = model.generate(**inputs, **kwargs)
except ValueError as e:
    if "only supports" in str(e):
        kwargs["num_beams"] = 1
        out = model.generate(**inputs, **kwargs)
    else:
        raise

Prevention

Query `getattr(type(model), '_supported_generation_modes', None)` before applying decoding recipes.
Keep per-model parameter presets instead of one shared generate config for heterogeneous model zoos.
Test each model class in your roster with the exact generation settings you ship.

When it happens

Trigger: Calling `generate` on a model that defines `_supported_generation_modes` with parameters that resolve to an excluded mode, e.g. `num_beams>1` (beam search), `assistant_model=...` (assisted generation), or contrastive-search settings, when the class only supports greedy/sample.

Common situations: Reusing a beam-search or speculative-decoding recipe from a mainstream LLM on a constrained architecture (some multimodal, stateful, or specialist models); upgrading transformers where the whitelist was added and previously-ignored modes now fail fast; batch pipelines assuming every model supports beam search.

Related errors

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