sgl-project/sglang · error · ValueError

Hunyuan3D only supports a single image input.

Error message

Hunyuan3D only supports a single image input.

What it means

The Hunyuan3D shape stage only supports conditioning from exactly one image. When image_path arrives as a list with a length other than 1 (including empty or multiple images), _validate_input rejects it before unpacking the single element. Batched/multi-image generation is not implemented for this model.

Source

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

        scheduler: Any,
        config: Hunyuan3D2PipelineConfig,
        latent_shape: tuple[int, ...],
        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(

View on GitHub (pinned to 0132848349)

Solutions

1. Send exactly one image path: image_path="/data/img.png" or image_path=["/data/img.png"]
2. If multiple candidates are needed, issue N separate requests each with one image
3. Adjust the client-side request schema to enforce maxItems=1 for this endpoint

Example fix

# before
req.image_path = ["a.png", "b.png"]

# after
req.image_path = ["a.png"]

imgs = req.image_path if isinstance(req.image_path, list) else [req.image_path]
assert len(imgs) == 1, "Hunyuan3D accepts exactly one image"

def is_single_image(path) -> bool:
    return isinstance(path, str) or (isinstance(path, list) and len(path) == 1)

When it happens

Trigger: Passing image_path as a list of 0 images or >=2 images, e.g. image_path=[] or image_path=["a.png","b.png"], or requesting num outputs implying multiple reference images.

Common situations: Reusing a generic multimodal request builder that always wraps images in a list; client sending multiple images expecting best-of-N; copy-pasting a batch-generation payload from a diffusion endpoint into the Hunyuan3D endpoint.

Related errors

• Hunyuan3D requires 'image_path' input.
• Hunyuan3D expects image_path as str, got {type(batch.image_p
• Hunyuan3D only supports num_outputs_per_prompt=1.
• unsupported input for causal Conv3D cat/pad CUDA
• unsupported input for usp_merge_heads CUDA

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