sgl-project/sglang · error · FileNotFoundError

Image path not found: {batch.image_path}

Error message

Image path not found: {batch.image_path}

What it means

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).

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py:160

        self.conditioner = conditioner
        self.scheduler = scheduler
        self.config = config
        self.latent_shape = latent_shape
        self.guidance_embed = guidance_embed

    def _validate_input(self, batch: Req, server_args: ServerArgs) -> None:
        if batch.image_path is None:
            raise ValueError("Hunyuan3D requires 'image_path' input.")
        if isinstance(batch.image_path, list):
            if len(batch.image_path) != 1:
                raise ValueError("Hunyuan3D only supports a single image input.")
            batch.image_path = batch.image_path[0]
        if not isinstance(batch.image_path, str):
            raise ValueError(
                f"Hunyuan3D expects image_path as str, got {type(batch.image_path)}"
            )
        if not os.path.exists(batch.image_path):
            raise FileNotFoundError(f"Image path not found: {batch.image_path}")
        if batch.num_outputs_per_prompt != 1:
            raise ValueError("Hunyuan3D only supports num_outputs_per_prompt=1.")

    def _prepare_latents(self, batch_size, dtype, device, generator, scheduler):
        from diffusers.utils.torch_utils import randn_tensor

        shape = (batch_size, *self.latent_shape)
        latents = randn_tensor(shape, generator=generator, device=device, dtype=dtype)
        return latents * getattr(scheduler, "init_noise_sigma", 1.0)

    def component_uses(
        self, server_args: ServerArgs, stage_name: str | None = None
    ) -> list[ComponentUse]:
        return [
            ComponentUse(
                self._component_stage_name(stage_name), "hy3dshape_conditioner"
            )
        ]

View on GitHub (pinned to 0132848349)

Solutions

1. Verify the file exists on the server: use absolute paths and check ls/path.exists on the host running sglang
2. Mount/copy the image directory into the container or shared storage the server can see
3. If uploading via API, upload the file first and pass the server-side stored path

Example fix

# before
req.image_path = "/home/user/pics/a.png"  # client path

# after
req.image_path = "/mnt/shared-uploads/a.png"  # path visible to server

import os
if not os.path.isfile(str(req.image_path)):
    raise FileNotFoundError(f"{req.image_path} not visible to server")

def path_exists_on_server(p: str) -> bool:
    return os.path.isfile(p)

try:
    out = stage.forward(batch, server_args)
except FileNotFoundError as e:
    log.error("image missing on server: %s", e); requeue_upload(e)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Prompt text file not found: {path}
• metal shader source not found: {metal_src}
• no safetensors files found in {quantized_path or component_m
• MiniMax H3 AdaLN cache does not exist: {self.path}
• The native SD2 UNet currently supports only the Hunyuan3D fo

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/9197153e0a94de55. Report an issue: GitHub.