sgl-project/sglang · error · ValueError

Hunyuan3D expects image_path as str, got

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.

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: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Every cache_salt should be a string.
• Expected a PIL image, got
• extra_key should be a list or a string.
• Hunyuan3D only supports a single image input.
• Hunyuan3D only supports num_outputs_per_prompt=1.

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

Appendix: 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)