huggingface/transformers · error · ValueError

Require guidance scale >1 to use the classifier free guidanc

Error message

Require guidance scale >1 to use the classifier free guidance processor, got guidance scale {guidance_scale}.

What it means

Error "Require guidance scale >1 to use the classifier free guidance processor, got guidance scale {guidance_scale}." thrown in huggingface/transformers.

Source

Thrown at src/transformers/generation/logits_process.py:2158

    >>> from transformers import AutoProcessor, MusicgenForConditionalGeneration

    >>> processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
    >>> model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")

    >>> inputs = processor(
    ...     text=["80s pop track with bassy drums and synth", "90s rock song with loud guitars and heavy drums"],
    ...     padding=True,
    ...     return_tensors="pt",
    ... )
    >>> audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)
    ```
    """

    def __init__(self, guidance_scale):
        if guidance_scale > 1:
            self.guidance_scale = guidance_scale
        else:
            raise ValueError(
                "Require guidance scale >1 to use the classifier free guidance processor, got guidance scale "
                f"{guidance_scale}."
            )

    @add_start_docstrings(LOGITS_PROCESSOR_INPUTS_DOCSTRING)
    def __call__(self, input_ids: torch.LongTensor, scores: torch.FloatTensor) -> torch.FloatTensor:
        # simple check to make sure we have compatible batch sizes between our
        # logits scores (cond + uncond) and input ids (cond only)
        if scores.shape[0] != 2 * input_ids.shape[0]:
            raise ValueError(
                f"Logits should have twice the batch size of the input ids, the first half of batches corresponding to "
                f"the conditional inputs, and the second half of batches corresponding to the unconditional inputs. Got "
                f"batch size {scores.shape[0]} for the logits and {input_ids.shape[0]} for the input ids."
            )
        unguided_bsz = scores.shape[0] // 2
        cond_logits, uncond_logits = scores.split(unguided_bsz, dim=0)
        scores_processed = uncond_logits + (cond_logits - uncond_logits) * self.guidance_scale
        return scores_processed

View on GitHub (pinned to a597f97485)

Solutions

1. Set `guidance_scale` to a value greater than 1 (e.g. 7.5) when using classifier-free guidance.
2. Remove the classifier-free guidance processor if guidance is not needed.

When it happens

Trigger: Raised in ClassifierFreeGuidanceLogitsProcessor.__init__ when guidance_scale <= 1.

Common situations: Classifier-free guidance decoding with guidance_scale set to 1.0 or lower, where CFG has no effect and the processor rejects it.

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