{"record":{"id":"bccb02125ae55155","repo":"sgl-project/sglang","slug":"hunyuan3d-only-supports-a-single-image-input","errorCode":null,"errorMessage":"Hunyuan3D only supports a single image input.","messagePattern":"Hunyuan3D only supports a single image input\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py","lineNumber":153,"sourceCode":"        scheduler: Any,\n        config: Hunyuan3D2PipelineConfig,\n        latent_shape: tuple[int, ...],\n        guidance_embed: bool,\n    ) -> None:\n        super().__init__()\n        self.image_processor = image_processor\n        self.conditioner = conditioner\n        self.scheduler = scheduler\n        self.config = config\n        self.latent_shape = latent_shape\n        self.guidance_embed = guidance_embed\n\n    def _validate_input(self, batch: Req, server_args: ServerArgs) -> None:\n        if batch.image_path is None:\n            raise ValueError(\"Hunyuan3D requires 'image_path' input.\")\n        if isinstance(batch.image_path, list):\n            if len(batch.image_path) != 1:\n                raise ValueError(\"Hunyuan3D only supports a single image input.\")\n            batch.image_path = batch.image_path[0]\n        if not isinstance(batch.image_path, str):\n            raise ValueError(\n                f\"Hunyuan3D expects image_path as str, got {type(batch.image_path)}\"\n            )\n        if not os.path.exists(batch.image_path):\n            raise FileNotFoundError(f\"Image path not found: {batch.image_path}\")\n        if batch.num_outputs_per_prompt != 1:\n            raise ValueError(\"Hunyuan3D only supports num_outputs_per_prompt=1.\")\n\n    def _prepare_latents(self, batch_size, dtype, device, generator, scheduler):\n        from diffusers.utils.torch_utils import randn_tensor\n\n        shape = (batch_size, *self.latent_shape)\n        latents = randn_tensor(shape, generator=generator, device=device, dtype=dtype)\n        return latents * getattr(scheduler, \"init_noise_sigma\", 1.0)\n\n    def component_uses(","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py#L135-L171","documentation":"The Hunyuan3D shape stage only supports conditioning from exactly one image. When image_path arrives as a list with a length other than 1 (including empty or multiple images), _validate_input rejects it before unpacking the single element. Batched/multi-image generation is not implemented for this model.","triggerScenarios":"Passing image_path as a list of 0 images or >=2 images, e.g. image_path=[] or image_path=[\"a.png\",\"b.png\"], or requesting num outputs implying multiple reference images.","commonSituations":"Reusing a generic multimodal request builder that always wraps images in a list; client sending multiple images expecting best-of-N; copy-pasting a batch-generation payload from a diffusion endpoint into the Hunyuan3D endpoint.","solutions":["Send exactly one image path: image_path=\"/data/img.png\" or image_path=[\"/data/img.png\"]","If multiple candidates are needed, issue N separate requests each with one image","Adjust the client-side request schema to enforce maxItems=1 for this endpoint"],"exampleFix":"# before\nreq.image_path = [\"a.png\", \"b.png\"]\n\n# after\nreq.image_path = [\"a.png\"]","handlingStrategy":"validation","validationCode":"imgs = req.image_path if isinstance(req.image_path, list) else [req.image_path]\nassert len(imgs) == 1, \"Hunyuan3D accepts exactly one image\"","typeGuard":"def is_single_image(path) -> bool:\n    return isinstance(path, str) or (isinstance(path, list) and len(path) == 1)","tryCatchPattern":null,"preventionTips":["Constrain image arrays to maxItems=1 in the request schema","Split multi-image requests into separate calls client-side"],"tags":["hunyuan3d","input-validation","single-image-constraint"],"backgroundTag":"input-cardinality-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}