Comfy-Org/ComfyUI · error · ValueError

Connect reference_audio inputs in order without gaps: refere

Error message

Connect reference_audio inputs in order without gaps: reference_audio_1, then _2, then _3.

What it means

The node collects connected reference_audio inputs as indices (1, 2, 3, ...). In 'audio reference' mode they must be contiguous starting at 1: audio_indices must equal list(range(1, len+1)). Gaps (e.g. only reference_audio_2 connected, or _1 and _3) are rejected because @Audio{N} tags map positionally to these inputs.

Source

Thrown at comfy_api_nodes/nodes_bytedance.py:3170

    preset_voice: str | None = None,
) -> None:
    validate_string(text_prompt, field_name="text_prompt", min_length=1, max_length=3000)
    max_tag = max_audio_tag(text_prompt)

    if mode == MODE_TEXT:
        if max_tag:
            raise ValueError(
                f"The prompt references @Audio{max_tag}, but reference mode is '{MODE_TEXT}'. "
                f"Switch to '{MODE_AUDIO}' and connect the reference clip(s)."
            )
    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.")

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Reconnect clips so inputs are filled in order: reference_audio_1 first, then _2, then _3, with no gaps.
If you need fewer references, move the later clips down to the lower-numbered inputs.

Defensive patterns

Strategy: validation

Validate before calling

if audio_indices != list(range(1, len(audio_indices) + 1)):
    raise ValueError("fill reference_audio inputs 1..N with no gaps")

Type guard

def audio_indices_contiguous(indices: list[int]) -> bool:
    return indices == list(range(1, len(indices) + 1))

Prevention

Always fill reference_audio inputs starting at _1, in order.
After deleting a clip, shift the remaining clips down to close the gap.

When it happens

Trigger: Connecting reference_audio_2 without reference_audio_1, or wiring _1 and _3 while leaving _2 empty, with mode='audio reference'.

Common situations: Deleting a middle audio node in the graph; users assuming any subset of the numbered inputs is valid; reconnecting clips after rearranging a workflow.

Related errors

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