sgl-project/sglang · error · ValueError

pixel_values and image_grid_thw must be given together

Error message

pixel_values and image_grid_thw must be given together

What it means

encode_ids requires pixel_values and image_grid_thw to be supplied together (both or neither). Passing only one indicates a malformed call — grid metadata is required to interpret image patches.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/encoders/minimax_h3_qwen3vl.py:341

            use_cache=False,
            **kwargs,
        )
        return BaseEncoderOutput(last_hidden_state=outputs.last_hidden_state)

    @torch.no_grad()
    def encode_ids(
        self,
        input_ids: torch.Tensor,
        *,
        pixel_values: torch.Tensor | None = None,
        image_grid_thw: torch.Tensor | None = None,
        pixel_values_videos: torch.Tensor | None = None,
        video_grid_thw: torch.Tensor | None = None,
    ) -> torch.Tensor:
        if input_ids.dim() != 1:
            raise ValueError(f"input_ids must be 1-D, got {list(input_ids.shape)}")
        if (pixel_values is None) != (image_grid_thw is None):
            raise ValueError("pixel_values and image_grid_thw must be given together")
        if (pixel_values_videos is None) != (video_grid_thw is None):
            raise ValueError(
                "pixel_values_videos and video_grid_thw must be given together"
            )

        host_ids = input_ids.to(device="cpu", dtype=torch.long)[None]
        host_image_grid_thw = (
            image_grid_thw.to(device="cpu", dtype=torch.long)
            if image_grid_thw is not None
            else None
        )
        host_video_grid_thw = (
            video_grid_thw.to(device="cpu", dtype=torch.long)
            if video_grid_thw is not None
            else None
        )
        position_ids = None
        if host_image_grid_thw is not None or host_video_grid_thw is not None:

View on GitHub (pinned to 0132848349)

Solutions

1. Pass image_grid_thw alongside pixel_values (take it from the processor output)
2. If there are no images, pass both as None

Example fix

# before
hidden = enc.encode_ids(ids, pixel_values=pv)
# after
hidden = enc.encode_ids(ids, pixel_values=pv, image_grid_thw=grid_thw)

assert (pixel_values is None) == (image_grid_thw is None)

When it happens

Trigger: encode_ids(..., pixel_values=t, image_grid_thw=None) or the reverse — exactly one of the pair given.

Common situations: Adapting call sites that previously passed only pixel tensors; optional-chaining bugs (e.g. `or None` collapsing an empty tensor); refactoring that dropped the grid tensor.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• pixel_values_videos and video_grid_thw must be given togethe
• input_ids must be 1-D, got {list(input_ids.shape)}
• unexpected hidden shape {list(hidden.shape)}, expected {expe
• fl2va requires first_frame, last_frame, or both
• ref2va requires at least one of reference_image, reference_v

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