Comfy-Org/ComfyUI · error · ValueError

Avatar '{avatar_label}' does not support the {engine} engine

Error message

Avatar '{avatar_label}' does not support the {engine} engine (supported: {', '.join(supported)}). Set engine to 'auto' to pick a compatible engine automatically.

What it means

Thrown during avatar resolution when the user explicitly selected an engine that the chosen avatar does not support. For catalog avatars the supported list comes from HEYGEN_AVATAR_MAP; for custom avatar ids it is fetched live via the avatar look endpoint (supported_api_engines). Only the explicit engine choice is validated; 'auto' silently picks the first supported of avatar_iv/avatar_iii/avatar_v.

Source

Thrown at comfy_api_nodes/nodes_heygen.py:116

        look = (
            await sync_op_raw(
                cls,
                ApiEndpoint(path=f"{_LOOKS_PATH}/{custom_avatar_id}"),
                final_label_on_success=None,
            )
        ).get("data") or {}
        avatar_id = custom_avatar_id
        avatar_label = look.get("name") or custom_avatar_id
        supported = look.get("supported_api_engines") or []
    else:
        avatar_id, avatar_type, supported = HEYGEN_AVATAR_MAP[avatar_label]

    if engine_choice == "auto":
        engine = next((e for e in ("avatar_iv", "avatar_iii", "avatar_v") if e in supported), None)
    else:
        engine = engine_choice
        if supported and engine not in supported:
            raise ValueError(
                f"Avatar '{avatar_label}' does not support the {engine} engine "
                f"(supported: {', '.join(supported)}). Set engine to 'auto' to pick "
                "a compatible engine automatically."
            )
    return avatar_id, engine


class HeyGenTalkingPhotoNode(IO.ComfyNode):
    """Animate a still image of a person into a lip-synced talking video."""

    @classmethod
    def define_schema(cls) -> IO.Schema:
        return IO.Schema(
            node_id="HeyGenTalkingPhotoNode",
            display_name="HeyGen Talking Photo",
            category="partner/video/HeyGen",
            description="Animate any image of a person into a lip-synced talking video "
            "(HeyGen Avatar IV). Drive it with a text script or your own audio.",

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Set engine to 'auto' — the node then picks the newest supported engine automatically
2. Choose an engine listed in the error's supported list
3. For custom avatars, verify the avatar's supported engines in the HeyGen dashboard before pinning an engine

Example fix

# before
engine_choice = "avatar_v"   # avatar only supports avatar_iii
# after
engine_choice = "auto"         # resolves to avatar_iii automatically

def engine_ok(engine_choice: str, supported: list[str]) -> bool:
    return engine_choice == 'auto' or not supported or engine_choice in supported

When it happens

Trigger: Setting the engine widget to e.g. 'avatar_v' while the selected avatar's supported_api_engines (or catalog entry) does not include it.

Common situations: Newer engines (avatar_iv/v) requested on legacy photo avatars; custom avatar imported from an older HeyGen account; mixing talking-photo avatars with avatar-video engines.

Related errors

• A voice is required when driving the video with a text scrip
• background_color must be a hex color code like '#00ff00'.
• HeyGen accepts at most 3 reference images; got {n_images}.
• Unsupported process_res_method: {method}
• At least 4 points are required to compute a homography.

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