Comfy-Org/ComfyUI · error · ValueError

Reference mode '{MODE_IMAGE}' requires a reference_image inp

Error message

Reference mode '{MODE_IMAGE}' requires a reference_image input.

What it means

Thrown by the ByteDance Seed Audio node when reference_mode is 'image reference' but no image is connected to the reference_image input. In this mode the model clones speech characteristics from a reference image, so the image is mandatory. Validation happens locally before the API request.

Source

Thrown at comfy_api_nodes/nodes_bytedance.py:3180

            )
    elif mode == MODE_AUDIO:
        if not audio_indices:
            raise ValueError(
                f"Reference mode '{MODE_AUDIO}' requires at least one reference_audio input "
                f"(or switch to '{MODE_TEXT}')."
            )
        if audio_indices != list(range(1, len(audio_indices) + 1)):
            raise ValueError(
                "Connect reference_audio inputs in order without gaps: reference_audio_1, then _2, then _3."
            )
        if max_tag > len(audio_indices):
            raise ValueError(
                f"The prompt references @Audio{max_tag}, but only {len(audio_indices)} "
                f"reference audio(s) are connected."
            )
    elif mode == MODE_IMAGE:
        if not has_image:
            raise ValueError(f"Reference mode '{MODE_IMAGE}' requires a reference_image input.")
        if max_tag:
            raise ValueError(
                f"@AudioN tags are not used in '{MODE_IMAGE}' mode; the prompt should contain "
                f"only the text to synthesize."
            )
    elif mode == MODE_SPEAKER:
        if not preset_voice or preset_voice not in SEED_AUDIO_VOICE_MAP:
            raise ValueError(f"Reference mode '{MODE_SPEAKER}' requires selecting a preset voice.")
        if max_tag > 1:
            raise ValueError(
                f"'{MODE_SPEAKER}' mode uses a single voice, so @Audio{max_tag} is out of range. "
                f"Remove the @AudioN tags — the whole prompt is read in the selected voice."
            )
    else:
        raise ValueError(f"Unknown reference mode: {mode!r}")


class ByteDanceSeedAudioNode(IO.ComfyNode):

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Connect an IMAGE output (e.g. Load Image) to the node's reference_image input.
If the upstream image node is bypassed or muted, unmute it or reconnect a live image source.
If you meant to use a voice clip or preset voice instead, switch reference_mode to 'audio reference' or 'preset voice'.

Defensive patterns

Strategy: validation

Validate before calling

def check_image_mode(mode: str, has_image: bool) -> None:
    if mode == "image reference" and not has_image:
        raise ValueError("image reference mode needs a reference_image connected")

Prevention

Whenever you switch reference_mode to 'image reference', immediately wire a reference_image.
Unmute/unbypass upstream image nodes before queueing the workflow.
Visually verify all required inputs on the node are connected before clicking Queue.

When it happens

Trigger: reference_mode == 'image reference' and the has_image flag is false because the reference_image input is unwired or resolves to nothing.

Common situations: User switches the mode dropdown from 'text only' to 'image reference' without wiring an image; an upstream image node is muted/bypassed so the image input is effectively empty; workflow copied without the image source node.

Related errors

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