Comfy-Org/ComfyUI · error · ValueError

Unknown reference mode: {mode!r}

Error message

Unknown reference mode: {mode!r}

What it means

Thrown by the ByteDance Seed Audio reference-mode validation when the mode string matches none of the four known modes ('text only', 'audio reference', 'image reference', 'preset voice'). The UI combo cannot normally produce this value, so it almost always indicates a hand-edited or version-mismatched workflow JSON.

Source

Thrown at comfy_api_nodes/nodes_bytedance.py:3195

            )
    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):

    @classmethod
    def define_schema(cls) -> IO.Schema:
        return IO.Schema(
            node_id="ByteDanceSeedAudio",
            display_name="ByteDance Seed Audio 1.0",
            category="partner/audio/ByteDance",
            description=(
                "Generate speech, music, sound effects and multi-speaker dialogue from a single prompt "
                "with ByteDance Seed Audio 1.0. Describe the voice(s), emotion, ambience, background music "
                "and sound effects in the prompt, and include the lines to speak. Optionally pick a built-in "
                "preset voice, clone voices from up to 3 reference clips (tagged @Audio1-3 in the prompt), "
                "or derive a voice from a character image. Up to 2 minutes of audio per run. "
                "The multilingual model supports 20 languages and timestamp-based timing control."
            ),

View on GitHub (pinned to 1c6d8d45b3)

Solutions

  1. Delete and re-add the node in the current ComfyUI version so the combo repopulates with valid mode labels.
  2. If driving via API, set reference_mode to one of: 'text only', 'audio reference', 'image reference', 'preset voice'.
  3. Check the workflow JSON for the reference_mode value and fix the typo or stale label.

Example fix

// before (API prompt): "reference_mode": "image"
// after (API prompt):  "reference_mode": "image reference"
Defensive patterns

Strategy: type-guard

Type guard

SEED_AUDIO_MODES = {"text only", "audio reference", "image reference", "preset voice"}

def is_valid_reference_mode(mode: str) -> bool:
    return mode in SEED_AUDIO_MODES

Prevention

When it happens

Trigger: reference_mode arrives as a string outside the four MODE_* constants, e.g. an old workflow saved with a different label, or a programmatic/validated_prompt API call passing an arbitrary string.

Common situations: Loading a workflow saved by a different ComfyUI version where mode labels were renamed; constructing the node input via the HTTP API with a typo'd mode string; manually editing workflow JSON.

Related errors

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