sgl-project/sglang · error · ValueError

Invalid Kimi image grid metadata: {values}; expected [h, w]

Error message

Invalid Kimi image grid metadata: {values}; expected [h, w] or [t, h, w]

What it means

Thrown by _kimi_hw_from_patch_grid when the flattened Kimi image grid metadata does not contain exactly 2 ([h, w]) or 3 ([t, h, w]) values. Kimi vision models attach a patch-grid tensor per image; h/w (and optional temporal t) are used to compute patch and token counts. Anything with a different element count (empty, scalar, 4+ values) is rejected.

Source

Thrown at python/sglang/srt/disaggregation/encoder/preprocessor.py:687

        if self.model_type == "kimi_vl" and modality == Modality.IMAGE:
            h, w = self._kimi_hw_from_patch_grid(grid)
            return h * w
        return int(grid[0] * grid[1] * grid[2])

    @staticmethod
    def _kimi_hw_from_patch_grid(
        grid: Union[torch.Tensor, np.ndarray, List[int], Tuple[int, ...]],
    ) -> Tuple[int, int]:
        """Extract (height, width) from Kimi 2D or 3D patch-grid metadata."""
        if isinstance(grid, torch.Tensor):
            values = grid.flatten().tolist()
        elif isinstance(grid, np.ndarray):
            values = grid.reshape(-1).tolist()
        else:
            values = np.asarray(grid).reshape(-1).tolist()

        if len(values) not in (2, 3):
            raise ValueError(
                f"Invalid Kimi image grid metadata: {values}; "
                "expected [h, w] or [t, h, w]"
            )
        return int(values[-2]), int(values[-1])

    def _kimi_tokens_from_patch_grid(self, grid: Union[torch.Tensor, List[int]]) -> int:
        """Calculate Kimi image tokens from either 2D or 3D patch metadata."""
        h, w = self._kimi_hw_from_patch_grid(grid)
        merge_h, merge_w = self.model_config.hf_config.vision_config.merge_kernel_size
        return (h * w) // (merge_h * merge_w)

    def get_num_tokens(
        self, grid: Union[torch.Tensor, List[int]], modality: Modality
    ) -> int:
        """Compatibility helper for callers that still provide patch grids."""
        if modality == Modality.AUDIO:
            input_length = self.get_num_patches(grid, modality)
            return self._get_feat_extract_output_lengths(input_length)

View on GitHub (pinned to 0132848349)

Solutions

1. Pass a per-image grid with exactly 2 or 3 entries, e.g. torch.tensor([t, h, w]) or [h, w].
2. If you have a batched grid tensor, index it per image (grid[i]) before calling get_num_patches/get_num_tokens.
3. Print the offending values (included in the message) and verify the vision processor output shape for Kimi models.
4. Ensure the grid is not None/empty before calling.

Example fix

# before
h, w = prep._kimi_hw_from_patch_grid(batched_grid)  # shape (N, 3)
# after
for g in batched_grid:
    h, w = prep._kimi_hw_from_patch_grid(g)  # each shape (3,)

def is_valid_kimi_grid(grid) -> bool:
    import numpy as np
    if hasattr(grid, "flatten"):
        vals = grid.flatten().tolist()
    else:
        vals = np.asarray(grid).reshape(-1).tolist()
    return len(vals) in (2, 3)

from typing import Union
import torch

def is_kimi_patch_grid(grid: Union[torch.Tensor, list, tuple]) -> bool:
    try:
        v = grid.flatten().tolist() if isinstance(grid, torch.Tensor) else list(grid)
    except Exception:
        return False
    return len(v) in (2, 3) and all(isinstance(x, (int, float)) for x in v)

try:
    h, w = prep._kimi_hw_from_patch_grid(grid)
except ValueError:
    raise ValueError(f"expected per-image [h,w] or [t,h,w] grid, got shape {getattr(grid, 'shape', grid)}")

When it happens

Trigger: Calling get_num_patches / get_num_tokens / _kimi_tokens_from_patch_grid on a kimi_vl / kimi_k25 / kimi_k3 model with a grid that is a scalar (e.g. audio-style feature length), an empty tensor, or a per-batch stacked tensor that flattens to more than 3 values (e.g. [b, t, h, w]).

Common situations: Feeding a batched grid (multiple images concatenated) instead of a per-image grid; passing an unflattened nested list; a corrupted or truncated grid tensor from the disaggregation transfer path; reusing a generic grid format from another model family with Kimi.

Related errors

• Grid dim ({_mm_grid_attrs[modality]}) not found in {mm_input
• Unsupported grid type for kimi image tokens: {type(grid_thw)
• Invalid grid metadata for kimi image tokens: {vals} (expecte
• txt_freqs_cis must be a 2D cos_sin_cache tensor
• The number of image placeholders exceeds img_grid_thw entrie

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