{"record":{"id":"2369430f664d7d70","repo":"huggingface/transformers","slug":"guidance-top-k-has-to-be-a-strictly-positive-int","errorCode":null,"errorMessage":"`guidance_top_k` has to be a strictly positive integer if given, but is {self.guidance_top_k}","messagePattern":"`guidance_top_k` has to be a strictly positive integer if given, but is (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/generation/logits_process.py","lineNumber":3039,"sourceCode":"            Higher guidance scale encourages the model to generate samples that are more closely linked to the input\n            prompt, usually at the expense of poorer quality.\n        guidance_top_k (int, *optional*):\n            The number of highest probability vocabulary tokens to keep for top-k-filtering. However, we do not keep\n            the logits of the combined CFG output, but the conditioned output only.\n    \"\"\"\n\n    def __init__(self, guidance_scale: float, guidance_top_k: int | None = None):\n        if guidance_scale > 1:\n            self.guidance_scale = guidance_scale\n        else:\n            raise ValueError(\n                \"Require guidance scale >1 to use the classifier free guidance processor, got guidance scale \"\n                f\"{guidance_scale}.\"\n            )\n\n        self.guidance_top_k = guidance_top_k\n        if self.guidance_top_k is not None and self.guidance_top_k < 1:\n            raise ValueError(\n                f\"`guidance_top_k` has to be a strictly positive integer if given, but is {self.guidance_top_k}\"\n            )\n\n    @add_start_docstrings(LOGITS_PROCESSOR_INPUTS_DOCSTRING)\n    def __call__(self, input_ids: torch.LongTensor, scores: torch.FloatTensor) -> torch.FloatTensor:\n        # simple check to make sure we have compatible batch sizes between our\n        # logits scores (cond + uncond) and input ids (cond only)\n        if scores.shape[0] != 2 * input_ids.shape[0]:\n            raise ValueError(\n                f\"Logits should have twice the batch size of the input ids, the first half of batches corresponding to \"\n                f\"the conditional inputs, and the second half of batches corresponding to the unconditional inputs. Got \"\n                f\"batch size {scores.shape[0]} for the logits and {input_ids.shape[0]} for the input ids.\"\n            )\n        # Base CFG with center on cond_logits\n        unguided_bsz = scores.shape[0] // 2\n        cond_logits, uncond_logits = scores.split(unguided_bsz, dim=0)\n        scores_processed = cond_logits + (cond_logits - uncond_logits) * self.guidance_scale\n","sourceCodeStart":3021,"sourceCodeEnd":3057,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/generation/logits_process.py#L3021-L3057","documentation":"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.","triggerScenarios":"Passing guidance_top_k=0, a negative int, or a value that decayed to <= 0 via a hyperparameter search sweep when constructing ClassifierFreeGuidanceLogitsProcessor.","commonSituations":"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.","solutions":["Pass a strictly positive integer, e.g. guidance_top_k=50, or omit the argument / pass None to disable top-k filtering.","If the value comes from a sweep, restrict the search space to integers >= 1.","Coerce near-zero floats: guidance_top_k = max(1, int(k)) only if that matches your intent."],"exampleFix":"# before\nprocessor = ClassifierFreeGuidanceLogitsProcessor(guidance_scale=7.5, guidance_top_k=0)\n\n# after\nprocessor = ClassifierFreeGuidanceLogitsProcessor(guidance_scale=7.5, guidance_top_k=50)","handlingStrategy":"validation","validationCode":"if guidance_top_k is not None:\n    assert isinstance(guidance_top_k, int) and guidance_top_k >= 1, \"guidance_top_k must be a positive int or None\"","typeGuard":"def valid_top_k(v) -> bool:\n    return v is None or (isinstance(v, int) and not isinstance(v, bool) and v >= 1)","tryCatchPattern":null,"preventionTips":["Use None (not 0) to disable top-k filtering.","Exclude 0 from top-k search spaces in hyperparameter sweeps.","Validate ints from config files before passing to library constructors."],"tags":["classifier-free-guidance","top-k","generation","config-validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}