{"record":{"id":"b6e4d2fa91ce0c0f","repo":"Comfy-Org/ComfyUI","slug":"reference-mode-mode-image-requires-a-reference","errorCode":null,"errorMessage":"Reference mode '{MODE_IMAGE}' requires a reference_image input.","messagePattern":"Reference mode '(.+?)' requires a reference_image input\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_bytedance.py","lineNumber":3180,"sourceCode":"            )\n    elif mode == MODE_AUDIO:\n        if not audio_indices:\n            raise ValueError(\n                f\"Reference mode '{MODE_AUDIO}' requires at least one reference_audio input \"\n                f\"(or switch to '{MODE_TEXT}').\"\n            )\n        if audio_indices != list(range(1, len(audio_indices) + 1)):\n            raise ValueError(\n                \"Connect reference_audio inputs in order without gaps: reference_audio_1, then _2, then _3.\"\n            )\n        if max_tag > len(audio_indices):\n            raise ValueError(\n                f\"The prompt references @Audio{max_tag}, but only {len(audio_indices)} \"\n                f\"reference audio(s) are connected.\"\n            )\n    elif mode == MODE_IMAGE:\n        if not has_image:\n            raise ValueError(f\"Reference mode '{MODE_IMAGE}' requires a reference_image input.\")\n        if max_tag:\n            raise ValueError(\n                f\"@AudioN tags are not used in '{MODE_IMAGE}' mode; the prompt should contain \"\n                f\"only the text to synthesize.\"\n            )\n    elif mode == MODE_SPEAKER:\n        if not preset_voice or preset_voice not in SEED_AUDIO_VOICE_MAP:\n            raise ValueError(f\"Reference mode '{MODE_SPEAKER}' requires selecting a preset voice.\")\n        if max_tag > 1:\n            raise ValueError(\n                f\"'{MODE_SPEAKER}' mode uses a single voice, so @Audio{max_tag} is out of range. \"\n                f\"Remove the @AudioN tags — the whole prompt is read in the selected voice.\"\n            )\n    else:\n        raise ValueError(f\"Unknown reference mode: {mode!r}\")\n\n\nclass ByteDanceSeedAudioNode(IO.ComfyNode):","sourceCodeStart":3162,"sourceCodeEnd":3198,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_bytedance.py#L3162-L3198","documentation":"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.","triggerScenarios":"reference_mode == 'image reference' and the has_image flag is false because the reference_image input is unwired or resolves to nothing.","commonSituations":"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.","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'."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"def check_image_mode(mode: str, has_image: bool) -> None:\n    if mode == \"image reference\" and not has_image:\n        raise ValueError(\"image reference mode needs a reference_image connected\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["comfyui","bytedance","seed-audio","validation","missing-input"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}