{"record":{"id":"fefcbf7090753fdb","repo":"huggingface/transformers","slug":"num-return-sequences-has-to-be-smaller-or-e","errorCode":null,"errorMessage":"`num_return_sequences` ({}) has to be smaller or equal to `num_beams` ({}).","messagePattern":"`num_return_sequences` \\((.+?)\\) has to be smaller or equal to `num_beams` \\((.+?)\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/generation/configuration_utils.py","lineNumber":801,"sourceCode":"            ):\n                minor_issues[\"length_penalty\"] = single_beam_wrong_parameter_msg.format(\n                    num_beams=self.num_beams, flag_name=\"length_penalty\", flag_value=self.length_penalty\n                )\n\n        # 2.4. check `num_return_sequences`\n        if self.num_return_sequences is not None and self.num_return_sequences > 1:\n            if self.num_beams is None or self.num_beams == 1:\n                if not self.do_sample:\n                    raise ValueError(\n                        \"Greedy methods (do_sample != True) without beam search do not support \"\n                        f\"`num_return_sequences` different than 1 (got {self.num_return_sequences}).\"\n                    )\n            elif (\n                self.num_beams is not None\n                and self.num_return_sequences is not None\n                and self.num_return_sequences > self.num_beams\n            ):\n                raise ValueError(\n                    f\"`num_return_sequences` ({self.num_return_sequences}) has to be smaller or equal to `num_beams` \"\n                    f\"({self.num_beams}).\"\n                )\n\n        # 2.5. check cache-related arguments\n        if self.use_cache is False:\n            # In this case, all cache-related arguments should be unset. However, since `use_cache=False` is often used\n            # passed to `generate` directly to hot-fix cache issues, let's raise a warning instead of an error\n            # (otherwise a user might need to overwrite several parameters).\n            no_cache_warning = (\n                \"You have not set `use_cache` to `True`, but {cache_arg} is set to {cache_arg_value}.\"\n                \"{cache_arg} will have no effect.\"\n            )\n            for arg_name in (\"cache_implementation\", \"cache_config\"):\n                if getattr(self, arg_name) is not None:\n                    minor_issues[arg_name] = no_cache_warning.format(\n                        cache_arg=arg_name, cache_arg_value=getattr(self, arg_name)\n                    )","sourceCodeStart":783,"sourceCodeEnd":819,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/generation/configuration_utils.py#L783-L819","documentation":"Raised by GenerationConfig.validate() when beam search is active (num_beams > 1) but num_return_sequences exceeds num_beams. Each return sequence is drawn from the beam set, so at most num_beams distinct sequences can be returned; requesting more is rejected as a configuration error.","triggerScenarios":"model.generate(num_beams=3, num_return_sequences=5) with do_sample False; a generation_config.json containing e.g. num_beams=2 and num_return_sequences=4; validate() during config load or save_pretrained.","commonSituations":"Tuning num_return_sequences up for batch generation while leaving num_beams from an earlier experiment; inheriting a beam-search config and adding sequence returns on top.","solutions":["Raise num_beams to at least num_return_sequences: model.generate(num_beams=5, num_return_sequences=5)","Or lower num_return_sequences to <= num_beams","Or switch to sampling (do_sample=True) where num_return_sequences is unconstrained by beams","Fix the offending values in the model's generation_config.json if they come from there"],"exampleFix":"# before\nout = model.generate(**inputs, num_beams=2, num_return_sequences=4)\n# after\nout = model.generate(**inputs, num_beams=4, num_return_sequences=4)","handlingStrategy":"validation","validationCode":"beams = cfg.num_beams or 1\nnrs = cfg.num_return_sequences or 1\nif beams > 1 and nrs > beams:\n    cfg.num_beams = nrs  # or clamp nrs","typeGuard":"def beams_ok(cfg) -> bool:\n    nrs = cfg.num_return_sequences or 1\n    return nrs <= 1 or (cfg.num_beams or 1) >= nrs or bool(cfg.do_sample)","tryCatchPattern":"try:\n    out = model.generate(**inputs, num_beams=2, num_return_sequences=4)\nexcept ValueError as e:\n    if 'num_return_sequences' in str(e) and 'num_beams' in str(e):\n        out = model.generate(**inputs, num_beams=4, num_return_sequences=4)\n    else:\n        raise","preventionTips":["Derive num_beams from num_return_sequences programmatically: num_beams=max(num_beams, num_return_sequences)","Validate the pair in unit tests of your generation pipeline"],"tags":["generation","beam-search","generation-config","validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}