Comfy-Org/ComfyUI · error · ValueError

A maximum of 7 reference images is supported; {total_images}

Error message

A maximum of 7 reference images is supported; {total_images} are connected.

What it means

Thrown by the Grok reference-image video node when the combined number of images across all reference_images slots exceeds 7. Each connected tensor's batch count is summed (sum of get_number_of_images over model['reference_images'].values()), matching xAI's limit of 7 reference images per request. The check runs before any upload, so it fails before spending API credits.

Source

Thrown at comfy_api_nodes/nodes_grok.py:992

                  $imgCost := $is15 ? 0.01 : 0.002;
                  $price := ($rate * $dur + $imgCost * $refs) * 1.43;
                  {"type":"usd","usd": $price}
                )
                """,
            ),
        )

    @classmethod
    async def execute(
        cls,
        prompt: str,
        model: dict,
        seed: int,
    ) -> IO.NodeOutput:
        validate_string(prompt, strip_whitespace=True, min_length=1)
        total_images = sum(get_number_of_images(t) for t in model["reference_images"].values())
        if total_images > 7:
            raise ValueError(f"A maximum of 7 reference images is supported; {total_images} are connected.")
        reference_audios = None
        if model["model"] == "grok-imagine-video-1.5":
            voices = [model.get(f"voice_{i}", "none") for i in range(1, 4)]
            reference_audios = [VoiceReferenceObject(voice_id=v) for v in voices if v != "none"] or None
            prompt = _normalize_grok_reference_prompt(prompt, total_images=total_images, voices=voices)
        ref_image_urls = await upload_images_to_comfyapi(
            cls,
            list(model["reference_images"].values()),
            mime_type="image/png",
            wait_label="Uploading base images",
            max_images=7,
        )
        initial_response = await sync_op(
            cls,
            ApiEndpoint(path="/proxy/xai/v1/videos/generations", method="POST"),
            data=VideoGenerationRequest(
                model=_GROK_VIDEO_MODEL_API_IDS.get(model["model"], model["model"]),
                reference_images=[InputUrlObject(url=i) for i in ref_image_urls],

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Reduce connected reference images so the total count (including batches) is at most 7
2. Split batched tensors and select only the needed frames before connecting
3. Curate the strongest 7 or fewer references; more images rarely improve identity fidelity

Example fix

// before: one reference_images slot receives a batch of 8 images -> error
// after: limit batch to 7 before connecting
// (workflow) Load Image batch=8 -> ImageBatchToImageList -> select 7 -> Grok reference images

from comfy_api_nodes.utils import get_number_of_images

def total_refs_ok(model: dict, limit: int = 7) -> bool:
    return sum(get_number_of_images(t) for t in model['reference_images'].values()) <= limit

When it happens

Trigger: Connecting several reference image inputs where the total image count (including multi-image batches in a single tensor) exceeds 7, on any model, but especially grok-imagine-video-1.5 workflows that use reference images.

Common situations: Feeding a batched tensor of character/scene references into one reference slot, or connecting many single-image slots each containing a multi-frame GIF.

Related errors

• 1080p resolution is only available for grok-imagine-video-1.
• Only one input image is supported.
• The prompt references @Image{idx}, but only {total_images} r
• The prompt references @Audio{idx}, but 'voice_{idx}' is set
• The prompt references @Audio{idx}, but only voices 1..{len(v

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