huggingface/transformers · error · ValueError

`guidance_top_k` has to be a strictly positive integer if gi

Error message

`guidance_top_k` has to be a strictly positive integer if given, but is {self.guidance_top_k}

What it means

Thrown by ClassifierFreeGuidanceLogitsProcessor.__init__ when guidance_top_k is given and is < 1. guidance_top_k optionally restricts the conditioned logits to the top-k tokens after CFG; k=0 or negative is not a valid filter size, so the constructor validates it early.

Source

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

            Higher guidance scale encourages the model to generate samples that are more closely linked to the input
            prompt, usually at the expense of poorer quality.
        guidance_top_k (int, *optional*):
            The number of highest probability vocabulary tokens to keep for top-k-filtering. However, we do not keep
            the logits of the combined CFG output, but the conditioned output only.
    """

    def __init__(self, guidance_scale: float, guidance_top_k: int | None = None):
        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}."
            )

        self.guidance_top_k = guidance_top_k
        if self.guidance_top_k is not None and self.guidance_top_k < 1:
            raise ValueError(
                f"`guidance_top_k` has to be a strictly positive integer if given, but is {self.guidance_top_k}"
            )

    @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."
            )
        # Base CFG with center on cond_logits
        unguided_bsz = scores.shape[0] // 2
        cond_logits, uncond_logits = scores.split(unguided_bsz, dim=0)
        scores_processed = cond_logits + (cond_logits - uncond_logits) * self.guidance_scale

View on GitHub (pinned to a597f97485)

Solutions

1. Pass a strictly positive integer, e.g. guidance_top_k=50, or omit the argument / pass None to disable top-k filtering.
2. If the value comes from a sweep, restrict the search space to integers >= 1.
3. Coerce near-zero floats: guidance_top_k = max(1, int(k)) only if that matches your intent.

Example fix

# before
processor = ClassifierFreeGuidanceLogitsProcessor(guidance_scale=7.5, guidance_top_k=0)

# after
processor = ClassifierFreeGuidanceLogitsProcessor(guidance_scale=7.5, guidance_top_k=50)

if guidance_top_k is not None:
    assert isinstance(guidance_top_k, int) and guidance_top_k >= 1, "guidance_top_k must be a positive int or None"

def valid_top_k(v) -> bool:
    return v is None or (isinstance(v, int) and not isinstance(v, bool) and v >= 1)

When it happens

Trigger: Passing guidance_top_k=0, a negative int, or a value that decayed to <= 0 via a hyperparameter search sweep when constructing ClassifierFreeGuidanceLogitsProcessor.

Common situations: Hyperparameter sweeps that include 0 in the top-k range; configs where guidance_top_k was intended as None (disabled) but serialized as 0; int truncation of a float like 0.5.

Related errors

• `top_k` has to be a strictly positive integer, but is {top_k
• `crop` was called, but the current layer does not track past
• Once the sliding window size has been reached, `DynamicSlidi
• `crop` was called, but the current layer does not track past
• Some generation parameters are set in the model config. Thes

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