{"record":{"id":"349dbceebd74aecc","repo":"huggingface/transformers","slug":"greedy-methods-do-sample-true-without-beam-se","errorCode":null,"errorMessage":"Greedy methods (do_sample != True) without beam search do not support `num_return_sequences` different than 1 (got {}).","messagePattern":"Greedy methods \\(do_sample != True\\) without beam search do not support `num_return_sequences` different than 1 \\(got (.+?)\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/generation/configuration_utils.py","lineNumber":792,"sourceCode":"                and _should_warn(\"num_beams\", \"early_stopping\", user_set_attributes)\n            ):\n                minor_issues[\"early_stopping\"] = single_beam_wrong_parameter_msg.format(\n                    num_beams=self.num_beams, flag_name=\"early_stopping\", flag_value=self.early_stopping\n                )\n            if (\n                self.length_penalty is not None\n                and self.length_penalty != 1.0\n                and _should_warn(\"num_beams\", \"length_penalty\", user_set_attributes)\n            ):\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).","sourceCodeStart":774,"sourceCodeEnd":810,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/generation/configuration_utils.py#L774-L810","documentation":"Raised by GenerationConfig.validate() when num_return_sequences > 1 but the decoding strategy is greedy search (do_sample is False/None and num_beams is None or 1). Greedy decoding is deterministic: with a single sequence path there is exactly one argmax continuation, so multiple return sequences cannot be produced. The library refuses the configuration instead of silently returning duplicate sequences.","triggerScenarios":"Calling model.generate(num_return_sequences=5) without setting do_sample=True or num_beams>=5; or loading a model whose generation_config.json sets num_return_sequences>1 while do_sample stays unset; validate() is invoked on GenerationConfig instantiation, .generate(), or save_pretrained(strict).","commonSituations":"Porting old sampling code where do_sample used to default to True; copying a generation_config.json from a sampling-tuned checkpoint onto a greedy model; setting num_return_sequences for data augmentation while forgetting sampling.","solutions":["Set do_sample=True (and typically temperature/top_p) when you want multiple diverse sequences: model.generate(..., do_sample=True, num_return_sequences=5)","Or use beam search: set num_beams >= num_return_sequences (e.g. num_beams=5, num_return_sequences=5)","Or reduce num_return_sequences to 1 if you only need greedy output","If the error comes from a saved generation_config.json, edit that file or override the attributes on model.generation_config before calling generate()"],"exampleFix":"# before\nout = model.generate(**inputs, num_return_sequences=4)\n# after\nout = model.generate(**inputs, do_sample=True, temperature=0.7, num_return_sequences=4)\n# or beam search\nout = model.generate(**inputs, num_beams=4, num_return_sequences=4)","handlingStrategy":"validation","validationCode":"def check_return_sequences(cfg):\n    nrs = cfg.num_return_sequences or 1\n    beams = cfg.num_beams or 1\n    if nrs > 1 and not cfg.do_sample and beams <= 1:\n        raise ValueError('num_return_sequences>1 requires do_sample=True or num_beams>=nrs')\n    return True","typeGuard":"def can_multi_return(cfg) -> bool:\n    nrs = cfg.num_return_sequences or 1\n    return nrs <= 1 or bool(cfg.do_sample) or (cfg.num_beams or 1) >= nrs","tryCatchPattern":"try:\n    model.generation_config.validate()\nexcept ValueError as e:\n    if 'num_return_sequences' in str(e):\n        model.generation_config.do_sample = True  # or set num_beams\n    else:\n        raise","preventionTips":["Always pair num_return_sequences>1 with do_sample=True or num_beams>=num_return_sequences","Call model.generation_config.validate() right after loading a model to catch bad saved configs early","Keep one source of truth for generation params and assert the invariant num_return_sequences <= max(1, num_beams) in tests"],"tags":["generation","generation-config","decoding","validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}