sgl-project/sglang · error · ValueError

Hunyuan3D requires 'image_path' input.

Error message

Hunyuan3D requires 'image_path' input.

What it means

Hunyuan3D's shape stage validates that the incoming request carries an image_path before it can run condition-image encoding. If batch.image_path is None the stage refuses to proceed because the model cannot generate a shape latent without a reference image. This is an input-contract error raised at the start of forward via _validate_input.

Source

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

        self,
        image_processor: Any,
        conditioner: Any,
        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)

View on GitHub (pinned to 0132848349)

Solutions

1. Set image_path (str or single-element list) on the request before invoking the Hunyuan3D pipeline
2. Check upstream request parsing/mapping code to confirm the client's image field is translated into batch.image_path
3. If routing requests programmatically, add a guard that only dispatches requests containing an image to the Hunyuan3D stage

Example fix

// before
req = Req(prompt="a chair")
out = hunyuan3d_stage.forward(req, server_args)

// after
req = Req(prompt="a chair", image_path="/data/chair.png")
out = hunyuan3d_stage.forward(req, server_args)

if batch.image_path is None:
    raise ValueError("image_path is required for Hunyuan3D") from None

def has_image_path(batch) -> bool:
    return batch.image_path is not None

When it happens

Trigger: Calling the Hunyuan3D pipeline (or its REST/API endpoint) with a request that omits image_path, or where upstream request parsing dropped/never set the image_path field on the Req object (e.g. a text-only request routed to the 3D shape stage).

Common situations: Client sends a generate request without the image input; a pipeline misconfiguration routes non-image requests to the Hunyuan3D shape stage; upstream stage fails to populate image_path after download; API schema confusion between image_url/image_path fields.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Unsupported image type: {type(image)}
• When using multiple prompts with multiple input images, prov
• {key}.position_ids is required
• {key}.{field} is required
• You have to specify input_ids

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