sgl-project/sglang · error · ValueError

Hunyuan3D expects image_path as str, got {type(batch.image_p

Error message

Hunyuan3D expects image_path as str, got {type(batch.image_path)}

What it means

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.

Source

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

        guidance_embed: bool,
    ) -> None:
        super().__init__()
        self.image_processor = image_processor
        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 [

View on GitHub (pinned to 0132848349)

Solutions

1. Convert the value to a string path before submitting: str(path) or payload["image"] as a plain string
2. If you have a PIL.Image or bytes, save to a file first and pass the file path
3. Align the API layer to pass image_path as str (or [str]) only

Example fix

# before
req.image_path = {"url": "https://example.com/a.png"}

# after
local = download("https://example.com/a.png")
req.image_path = local  # str path

p = req.image_path[0] if isinstance(req.image_path, list) else req.image_path
if not isinstance(p, str):
    p = str(p)
req.image_path = p

def is_str_path(p) -> bool:
    return isinstance(p, str)

When it happens

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

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

Understand the failure class

Background: "Wrong argument type", "must be a string", "expected Array or Prism::Scope": TypeError and ArgumentError when a library receives a value of the wrong type — this error's family across 28 libraries.

Related errors

• Unsupported image type: {type(image)}
• Hunyuan3D requires 'image_path' input.
• Hunyuan3D only supports a single image input.
• Hunyuan3D only supports num_outputs_per_prompt=1.
• extra_key should be a list or a string.

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