What causes "Invalid image data: {image_data}" in sgl-project/sglang?

Pass image_data as a list of image URLs / PIL images / base64 strings, or a single URL string

sgl-project/sglang · error · ValueError

Invalid image data: {image_data}

Error message

Invalid image data: {image_data}

What it means

The LLaVA processor dispatches on the type of image_data: a list, a single string/URL, etc. If image_data does not match any known shape (not a list, not a string, not None in the expected branch), the processor rejects it as invalid.

Source

Thrown at python/sglang/srt/multimodal/processors/llava.py:240

                        self._process_single_image(
                            img_data, aspect_ratio, grid_pinpoints
                        )
                    )

                res = await asyncio.gather(*res)
                for pixel_v, image_h, image_s in res:
                    pixel_values.append(pixel_v)
                    data_hashes.append(image_h)
                    image_sizes.append(image_s)
            else:
                # A single image
                pixel_values, image_hash, image_size = await self._process_single_image(
                    image_data[0], aspect_ratio, grid_pinpoints
                )
                pixel_values = [pixel_values]
                image_sizes = [image_size]
        else:
            raise ValueError(f"Invalid image data: {image_data}")
        modality = Modality.IMAGE
        if isinstance(request_obj.modalities, list):
            if request_obj.modalities[0] == "video":
                modality = Modality.VIDEO

        # Create one item per image for better cache granularity
        mm_items = []
        for pixel_v, image_s in zip(pixel_values, image_sizes):
            # Ensure ndim=4 so the model forward takes the correct encode branch
            if isinstance(pixel_v, np.ndarray) and pixel_v.ndim == 3:
                pixel_v = np.expand_dims(pixel_v, 0)
            mm_items.append(
                MultimodalDataItem(
                    feature=pixel_v,
                    model_specific_data={
                        "image_sizes": [image_s],
                        "image_aspect_ratio": aspect_ratio,
                    },

View on GitHub (pinned to 0132848349)

Solutions

Pass image_data as a list of image URLs / PIL images / base64 strings, or a single URL string
If using bytes, encode to a data URI or base64 string as the API expects
Inspect the type of image_data right before the call and normalize it

Example fix

# before
image_data = {"url": "https://example.com/cat.png"}  # dict -> error
# after
image_data = ["https://example.com/cat.png"]

Defensive patterns

Strategy: type-guard

Validate before calling

ok = image_data is None or isinstance(image_data, (str, list)) and all(isinstance(i, (str, bytes)) for i in (image_data if isinstance(image_data, list) else []))

Type guard

def is_valid_image_data(d) -> bool:
    if d is None: return True
    if isinstance(d, str): return True
    if isinstance(d, list): return all(isinstance(i, (str, bytes)) for i in d)
    return False

Prevention

Normalize all client images to a list of URL/base64 strings before calling the API
Never pass dicts or raw ints as image_data

When it happens

Trigger: Passing image_data of an unsupported type to process_mm_data_async, e.g. an int, dict, raw bytes, or a numpy array instead of the expected list of images/URLs or a single URL string.

Common situations: Client serializes images to base64 bytes or wraps them in a dict like {"url": ...} and passes that directly; or passes None through a code path that reaches the else branch.

Related errors

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