{"record":{"id":"f9cdd26a92230473","repo":"huggingface/transformers","slug":"textdiffusionstreamer-only-supports-batch-size-1","errorCode":null,"errorMessage":"TextDiffusionStreamer only supports batch size 1","messagePattern":"TextDiffusionStreamer only supports batch size 1","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/generation/streamers.py","lineNumber":384,"sourceCode":"        # we recommend setting it to `False` by default.\n        self._takes_logits = False\n        self.sleep_time = sleep_time\n\n    def _clear_draft(self):\n        if self._has_draft:\n            # Restore cursor and clear to end of screen\n            print(\"\\0338\\033[J\", end=\"\", flush=True)\n            self._has_draft = False\n\n    def put_draft(self, value, **kwargs):\n        \"\"\"\n        Receives the full sequence of draft tokens, decodes them, and prints them in yellow.\n        Overwrites previous draft.\n        \"\"\"\n        self._clear_draft()\n\n        if len(value.shape) > 1 and value.shape[0] > 1:\n            raise ValueError(\"TextDiffusionStreamer only supports batch size 1\")\n        elif len(value.shape) > 1:\n            value = value[0]\n\n        text = self.tokenizer.decode(value, **self.decode_kwargs)\n\n        # Save cursor position\n        print(\"\\0337\", end=\"\", flush=True)\n        # Print draft in yellow\n        print(f\"\\033[33m{text}\\033[0m\", end=\"\", flush=True)\n        self._has_draft = True\n        if self.sleep_time is not None:\n            time.sleep(self.sleep_time)\n\n    def put(self, value):\n        \"\"\"Receives confirmed tokens, clears draft, and prints them permanently.\"\"\"\n        self._clear_draft()\n        super().put(value)\n","sourceCodeStart":366,"sourceCodeEnd":402,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/generation/streamers.py#L366-L402","documentation":"ValueError from TextDiffusionStreamer.put_draft: like TextStreamer, the diffusion streamer prints a single evolving draft to stdout, so draft token batches with batch dimension > 1 are rejected. Drafts overwrite each other via ANSI cursor save/restore, which is inherently single-stream.","triggerScenarios":"Calling put_draft(value) with value.shape[0] > 1 in a text-diffusion generation loop (e.g. diffuLLaMA-style models) that was batched; passing the raw (batch, seq) tensor when only row 0 was intended.","commonSituations":"Reusing a batched diffusion pipeline with the visual streamer; forgetting to slice value[0] before put_draft in a custom loop.","solutions":["Run diffusion generation with batch size 1 when using TextDiffusionStreamer.","Detach the streamer for batched runs.","If you only care about one sample, index the batch before calling put_draft."],"exampleFix":"# before\nstreamer.put_draft(draft_tokens)  # (B>1, seq)\n\n# after\nstreamer.put_draft(draft_tokens[0:1])","handlingStrategy":"validation","validationCode":"if value.dim() > 1 and value.shape[0] > 1:\n    raise ValueError(\"TextDiffusionStreamer requires batch size 1; slice the batch first\")\n# or simply: value = value[:1]","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Reserve the diffusion streamer for interactive single-sample runs.","Slice draft tensors to [0:1] before put_draft in batched experiments."],"tags":["streamer","text-diffusion","batch-size","generation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}