{"record":{"id":"9197153e0a94de55","repo":"sgl-project/sglang","slug":"image-path-not-found-batch-image-path","errorCode":null,"errorMessage":"Image path not found: {batch.image_path}","messagePattern":"Image path not found: (.+?)","errorType":"validation","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py","lineNumber":160,"sourceCode":"        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 [\n            ComponentUse(\n                self._component_stage_name(stage_name), \"hy3dshape_conditioner\"\n            )\n        ]","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py#L142-L178","documentation":"The stage checks os.path.exists on the provided image path and raises FileNotFoundError when the file is absent. The Hunyuan3D shape stage reads the conditioning image from local disk, so the path must reference an existing readable file on the machine running the pipeline (not the client).","triggerScenarios":"Passing a path that does not exist on the server filesystem: typos, client-local paths, paths inside a container/volume not mounted, or files deleted between submission and execution.","commonSituations":"Running the server in Docker where the image directory is not mounted; passing a client-side absolute path to a remote server; race where a temp file was cleaned up; wrong working directory with relative paths.","solutions":["Verify the file exists on the server: use absolute paths and check ls/path.exists on the host running sglang","Mount/copy the image directory into the container or shared storage the server can see","If uploading via API, upload the file first and pass the server-side stored path"],"exampleFix":"# before\nreq.image_path = \"/home/user/pics/a.png\"  # client path\n\n# after\nreq.image_path = \"/mnt/shared-uploads/a.png\"  # path visible to server","handlingStrategy":"validation","validationCode":"import os\nif not os.path.isfile(str(req.image_path)):\n    raise FileNotFoundError(f\"{req.image_path} not visible to server\")","typeGuard":"def path_exists_on_server(p: str) -> bool:\n    return os.path.isfile(p)","tryCatchPattern":"try:\n    out = stage.forward(batch, server_args)\nexcept FileNotFoundError as e:\n    log.error(\"image missing on server: %s\", e); requeue_upload(e)","preventionTips":["Use absolute paths on shared/mounted storage","Upload images through the API rather than referencing client-local paths"],"tags":["hunyuan3d","file-not-found","filesystem","docker"],"backgroundTag":"file-path-not-found","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}