What causes "The maximum number of reference images is 10." in Comfy-Org/ComfyUI?

Trim the batch to at most 10 references

Comfy-Org/ComfyUI · error · ValueError

The maximum number of reference images is 10.

Error message

The maximum number of reference images is 10.

What it means

Raised by OmniProImageNode.execute when reference_images contains more than 10 images. The omni image endpoint allows up to 10 image references per request; the count is checked with get_number_of_images before upload.

Source

Thrown at comfy_api_nodes/nodes_kling.py:1441

    async def execute(
        cls,
        model_name: str,
        prompt: str,
        resolution: str,
        aspect_ratio: str,
        series_amount: str = "disabled",
        reference_images: Input.Image | None = None,
        seed: int = 0,
    ) -> IO.NodeOutput:
        _ = seed
        if model_name == "kling-image-o1" and resolution == "4K":
            raise ValueError("4K resolution is not supported for kling-image-o1 model.")
        prompt = normalize_omni_prompt_references(prompt)
        validate_string(prompt, min_length=1, max_length=2500)
        image_list: list[OmniImageParamImage] = []
        if reference_images is not None:
            if get_number_of_images(reference_images) > 10:
                raise ValueError("The maximum number of reference images is 10.")
            for i in reference_images:
                validate_image_dimensions(i, min_width=300, min_height=300)
                validate_image_aspect_ratio(i, (1, 2.5), (2.5, 1))
            for i in await upload_images_to_comfyapi(cls, reference_images, wait_label="Uploading reference image"):
                image_list.append(OmniImageParamImage(image=i))
        use_series = series_amount != "disabled"
        if use_series and model_name == "kling-image-o1":
            raise ValueError("kling-image-o1 does not support series generation.")
        response = await sync_op(
            cls,
            ApiEndpoint(path="/proxy/kling/v1/images/omni-image", method="POST"),
            response_model=TaskStatusResponse,
            data=OmniProImageRequest(
                model_name=model_name,
                prompt=prompt,
                resolution=resolution.lower(),
                aspect_ratio=aspect_ratio,
                image_list=image_list if image_list else None,

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Trim the batch to at most 10 references
Pre-filter the folder (remove dupes/thumbnails) and pin an explicit file list
Reduce reliance on references by describing key attributes in the prompt

Example fix

# before
reference_images = product_shots.images  # 14 images

# after
reference_images = product_shots.images[:10]  # <= 10

Defensive patterns

Strategy: validation

Validate before calling

def reference_count_ok_omni_image(reference_images) -> bool:
    return reference_images is None or get_number_of_images(reference_images) <= 10

Prevention

Pin explicit file lists instead of wildcard folders for references
Slice batches to 10 at the loader, not at the node

When it happens

Trigger: Connecting an 11+ image batch to reference_images on the omni image generation node.

Common situations: Whole-folder loaders with unsorted contents, or batched product-photo sets, silently exceed the cap.

Related errors

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/183d8d3b521f5d20. Report an issue: GitHub.