{"record":{"id":"1e90f0aee723690a","repo":"sgl-project/sglang","slug":"hunyuan3d-expects-image-path-as-str-got-type-bat","errorCode":null,"errorMessage":"Hunyuan3D expects image_path as str, got {type(batch.image_path)}","messagePattern":"Hunyuan3D expects image_path as str, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py","lineNumber":156,"sourceCode":"        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(\n        self, server_args: ServerArgs, stage_name: str | None = None\n    ) -> list[ComponentUse]:\n        return [","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py#L138-L174","documentation":"After list-unpacking, image_path must be a plain string filesystem path. If it is any other type (int, dict, PIL object, bytes, URL object, etc.) the stage raises this ValueError because it only knows how to load from a local path string. Remote URLs are not accepted here.","triggerScenarios":"Passing image_path as a URL string is fine type-wise, but passing a dict like {\"url\": ...}, a bytes blob, a PIL.Image, or a Path-like non-str object triggers this. The check is isinstance(batch.image_path, str) after list normalization.","commonSituations":"Client wraps the image in a JSON object; a Path object from pathlib not converted with str(); passing raw binary data instead of a saved file; schema drift between an HTTP API layer and the internal Req type.","solutions":["Convert the value to a string path before submitting: str(path) or payload[\"image\"] as a plain string","If you have a PIL.Image or bytes, save to a file first and pass the file path","Align the API layer to pass image_path as str (or [str]) only"],"exampleFix":"# before\nreq.image_path = {\"url\": \"https://example.com/a.png\"}\n\n# after\nlocal = download(\"https://example.com/a.png\")\nreq.image_path = local  # str path","handlingStrategy":"type-guard","validationCode":"p = req.image_path[0] if isinstance(req.image_path, list) else req.image_path\nif not isinstance(p, str):\n    p = str(p)\nreq.image_path = p","typeGuard":"def is_str_path(p) -> bool:\n    return isinstance(p, str)","tryCatchPattern":null,"preventionTips":["Normalize image inputs to str at the API boundary","Convert pathlib.Path with str() before building the request"],"tags":["hunyuan3d","type-error","input-validation"],"backgroundTag":"wrong-argument-type","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}