Comfy-Org/ComfyUI · error · ValueError

The prompt references @Image{idx}, but only {total_images} r

Error message

The prompt references @Image{idx}, but only {total_images} reference images are connected (a batched input counts once per image).

What it means

In the Grok audio/video prompt preprocessing, @ImageN reference tags are rewritten to internal <IMAGE_{N-1}> markers. If the prompt references an image index greater than the number of connected reference images (total_images), rewriting fails with this error. Note the semantics: a batched input counts once per image in total_images, so the check is against the flattened count.

Source

Thrown at comfy_api_nodes/nodes_grok.py:111

def _normalize_grok_reference_prompt(prompt: str, total_images: int, voices: list[str]) -> str:
    """Rewrite @Image1/@Audio1 style references (1-based, shared partner-node syntax)
    into Grok's native <IMAGE_0>/<AUDIO_0> tags; an unnumbered @image/@audio means the first one.
    Native tags pass through untouched. @ImageN refers to the Nth reference image overall, in
    input order — a batched input contributes one number per image. @AudioN refers to the
    'voice_N' widget; the API only accepts compact arrays, so voices are remapped to array
    positions and 'none' slots between selected voices are harmless. Substitution repeats until
    stable so adjacent tags like '@Image1@Image2' all resolve."""
    audio_indices: dict[int, int] = {}
    for slot, voice in enumerate(voices, start=1):
        if voice != "none":
            audio_indices[slot] = len(audio_indices)

    def repl(match: re.Match) -> str:
        kind = match.group(1).lower()
        idx = int(match.group("idx") or 1)
        if kind == "image":
            if not 1 <= idx <= total_images:
                raise ValueError(
                    f"The prompt references @Image{idx}, but only {total_images} "
                    f"reference images are connected (a batched input counts once per image)."
                )
            return f"<IMAGE_{idx - 1}>"
        if idx not in audio_indices:
            if 1 <= idx <= len(voices):
                raise ValueError(f"The prompt references @Audio{idx}, but 'voice_{idx}' is set to 'none'.")
            raise ValueError(f"The prompt references @Audio{idx}, but only voices 1..{len(voices)} exist.")
        return f"<AUDIO_{audio_indices[idx]}>"

    prev = None
    while prev != prompt:
        prev = prompt
        prompt = _GROK_REF_TAG_RE.sub(repl, prompt)
    return prompt


def _extract_grok_price(response) -> float | None:

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Fix the tag to reference an existing image: 1..total_images (1-based).
2. Connect the missing reference image(s) so the index becomes valid.
3. Remove stale @Image tags if the referenced image is intentionally gone.

Example fix

# before (only 2 reference images connected)
prompt = "blend @Image1 and @Image3 styles"  # raises

# after
prompt = "blend @Image1 and @Image2 styles"

import re
_TAG = re.compile(r"(?<!\w)@image(?P<idx>\d*)(?!\w)", re.IGNORECASE)
refs = {int(m.group("idx") or 1) for m in _TAG.finditer(prompt)}
bad = [i for i in refs if not 1 <= i <= total_images]
assert not bad, f"prompt references missing images {bad}; connected={total_images}"

When it happens

Trigger: A prompt containing '@Image5' (or '@Image' which defaults to idx 1 with total_images == 0) where the connected reference images number fewer than 5. _GROK_REF_TAG_RE matches @image/@Image with optional digits, case-insensitive; substitution loops until stable so adjacent tags all get resolved.

Common situations: Editing a prompt template written for more images than are currently wired; forgetting that unplugging one image socket shifts valid indices; batched tensor counted per image causing an off-by-N when a batch is replaced by a single image; typos like '@Image9' for '@Image0'.

Related errors

• The prompt references @Audio{idx}, but 'voice_{idx}' is set
• The prompt references @Audio{idx}, but only voices 1..{len(v
• The pro model supports only 1 input image.
• A maximum of 3 input images is supported.
• Custom aspect ratio is only allowed when multiple images are

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