{"record":{"id":"00c78b114731de01","repo":"sgl-project/sglang","slug":"hunyuan3d-requires-image-path-input","errorCode":null,"errorMessage":"Hunyuan3D requires 'image_path' input.","messagePattern":"Hunyuan3D requires 'image_path' 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":150,"sourceCode":"        self,\n        image_processor: Any,\n        conditioner: Any,\n        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)","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py#L132-L168","documentation":"Hunyuan3D's shape stage validates that the incoming request carries an image_path before it can run condition-image encoding. If batch.image_path is None the stage refuses to proceed because the model cannot generate a shape latent without a reference image. This is an input-contract error raised at the start of forward via _validate_input.","triggerScenarios":"Calling the Hunyuan3D pipeline (or its REST/API endpoint) with a request that omits image_path, or where upstream request parsing dropped/never set the image_path field on the Req object (e.g. a text-only request routed to the 3D shape stage).","commonSituations":"Client sends a generate request without the image input; a pipeline misconfiguration routes non-image requests to the Hunyuan3D shape stage; upstream stage fails to populate image_path after download; API schema confusion between image_url/image_path fields.","solutions":["Set image_path (str or single-element list) on the request before invoking the Hunyuan3D pipeline","Check upstream request parsing/mapping code to confirm the client's image field is translated into batch.image_path","If routing requests programmatically, add a guard that only dispatches requests containing an image to the Hunyuan3D stage"],"exampleFix":"// before\nreq = Req(prompt=\"a chair\")\nout = hunyuan3d_stage.forward(req, server_args)\n\n// after\nreq = Req(prompt=\"a chair\", image_path=\"/data/chair.png\")\nout = hunyuan3d_stage.forward(req, server_args)","handlingStrategy":"validation","validationCode":"if batch.image_path is None:\n    raise ValueError(\"image_path is required for Hunyuan3D\") from None","typeGuard":"def has_image_path(batch) -> bool:\n    return batch.image_path is not None","tryCatchPattern":null,"preventionTips":["Validate required fields before dispatching to model-specific stages","Add request-schema checks at the API layer per model endpoint"],"tags":["hunyuan3d","input-validation","multimodal","missing-argument"],"backgroundTag":"missing-required-parameter","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}