sgl-project/sglang · error · ValueError

The number of image placeholders exceeds img_grid_thw entrie

Error message

The number of image placeholders exceeds img_grid_thw entries.

What it means

While expanding Kimi image placeholders into per-image token spans, the input prompt contains more image_token_id tokens than there are img_grid_thw entries. The loop runs out of grid-derived token counts and cannot fill the next placeholder, so it raises.

Source

Thrown at python/sglang/srt/multimodal/processors/kimi_common.py:110

        if not isinstance(prompt, list):
            prompt = self._tokenizer.encode(prompt)

        image_token_counts = [
            self._num_image_tokens_from_grid(grid) for grid in img_grid_thw
        ]

        input_ids = []
        offsets = []
        img_idx = 0

        for token in prompt:
            if token != image_token_id:
                input_ids.append(token)
                continue

            if img_idx >= len(image_token_counts):
                raise ValueError(
                    "The number of image placeholders exceeds img_grid_thw entries."
                )

            num_tokens = image_token_counts[img_idx]
            start = len(input_ids)
            input_ids.extend([image_token_id] * num_tokens)
            offsets.append((start, len(input_ids) - 1))
            img_idx += 1

        if img_idx != len(image_token_counts):
            raise ValueError(
                "The number of image placeholders does not match img_grid_thw entries."
            )

        image_embeddings = embeddings[Modality.IMAGE]
        mm_items = []
        consumed = 0
        for start, end in offsets:

View on GitHub (pinned to 0132848349)

Solutions

1. Make the number of placeholder tokens in the prompt equal len(img_grid_thw) / the number of images
2. Regenerate the prompt with the current chat template after changing the image list
3. Add a pre-flight assert: placeholder_count == len(image_token_counts)

Example fix

// before
prompt = f"{IMG} {IMG} look"  # 2 placeholders, 1 image
build_from_grids(prompt, grids=[g1])

// after
prompt = f"{IMG} look"  # 1 placeholder, 1 image
build_from_grids(prompt, grids=[g1])

n_ph = sum(1 for t in input_ids if t == image_token_id)
assert n_ph <= len(image_token_counts), f"{n_ph} placeholders > {len(image_token_counts)} grids"

When it happens

Trigger: Calling get_mm_data / _build_kimi_mm_data_from_grids where the tokenized prompt has N image placeholder tokens but image_token_counts (from img_grid_thw) has fewer than N entries.

Common situations: Hardcoded prompts with extra <img> tokens, chat templates emitting one placeholder per image while the client sent fewer images/grids, or stale tokenized prompts reused after the image list changed.

Related errors

• The number of image placeholders does not match img_grid_thw
• Kimi image placeholders must map one-to-one to image data: e
• Grid dim ({_mm_grid_attrs[modality]}) not found in {mm_input
• Invalid grid metadata for kimi image tokens: {vals} (expecte
• Expected {len(image_token_counts)} image placeholder token(s

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