sgl-project/sglang · error · ValueError

The number of image placeholders does not match img_grid_thw

Error message

The number of image placeholders does not match img_grid_thw entries.

What it means

The Kimi placeholder-expansion loop finished but consumed fewer placeholders than the number of grid-derived image token counts: img_idx != len(image_token_counts). This is the mirror of the exceeds case — the prompt has fewer image_token_id tokens than images/grids supplied.

Source

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

        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:
            num_tokens = end - start + 1
            embedding_slice = image_embeddings[consumed : consumed + num_tokens]
            consumed += num_tokens
            mm_items.append(
                MultimodalDataItem(
                    modality=Modality.IMAGE,
                    offsets=[(start, end)],
                    precomputed_embeddings=embedding_slice,
                )
            )

View on GitHub (pinned to 0132848349)

Solutions

1. Ensure exactly one image placeholder token per image in the prompt
2. If images were removed, also remove their grid entries so counts align
3. Pre-validate: count of image_token_id in input_ids == len(image_token_counts) before calling

Example fix

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

// after
prompt = f"{IMG} {IMG} look"  # 2 placeholders, 2 images
build_from_grids(prompt, grids=[g1, g2])

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 with a prompt containing fewer image placeholder tokens than img_grid_thw entries (extra images passed but no placeholders for them).

Common situations: Sending multiple images with a template that only emits one placeholder, dropping placeholder tokens during custom prompt assembly, or images appended to image_data without updating the prompt.

Related errors

• The number of image placeholders exceeds img_grid_thw entrie
• 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/6103f65cb1eaf3e9. Report an issue: GitHub.