{"record":{"id":"cce606bdb4fd99cd","repo":"Comfy-Org/ComfyUI","slug":"heygen-did-not-return-an-avatar-created","errorCode":null,"errorMessage":"HeyGen did not return an avatar: {created}","messagePattern":"HeyGen did not return an avatar: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_heygen.py","lineNumber":561,"sourceCode":"            payload[\"prompt\"] = source[\"prompt\"]\n            ref_tensors = [t for t in (source.get(\"reference_images\") or {}).values() if t is not None]\n            if ref_tensors:\n                n_images = sum(get_number_of_images(t) for t in ref_tensors)\n                if n_images > 3:\n                    raise ValueError(f\"HeyGen accepts at most 3 reference images; got {n_images}.\")\n                scaled = [downscale_image_tensor_by_max_side(t, max_side=2000) for t in ref_tensors]\n                ref_urls = await upload_images_to_comfyapi(\n                    cls, scaled, max_images=3, mime_type=\"image/png\", total_pixels=None\n                )\n                payload[\"reference_images\"] = [{\"type\": \"url\", \"url\": u} for u in ref_urls]\n        created = await sync_op_raw(\n            cls,\n            ApiEndpoint(path=_AVATARS_PATH, method=\"POST\"),\n            data=payload,\n        )\n        look_id = ((created.get(\"data\") or {}).get(\"avatar_item\") or {}).get(\"id\")\n        if not look_id:\n            raise ValueError(f\"HeyGen did not return an avatar: {created}\")\n        final = await poll_op_raw(\n            cls,\n            ApiEndpoint(path=f\"{_LOOKS_PATH}/{look_id}\"),\n            # A missing status means the look needed no training and is ready.\n            status_extractor=lambda r: (r.get(\"data\") or {}).get(\"status\") or \"completed\",\n            failed_statuses=[\"failed\", \"pending_consent\"],\n            poll_interval=5.0,\n        )\n        data = final[\"data\"]\n        if data.get(\"preview_image_url\"):\n            preview = await download_url_to_image_tensor(data[\"preview_image_url\"])\n        else:\n            preview = torch.zeros(1, 64, 64, 3)\n        PromptServer.instance.send_progress_text(\n            f\"Please save the avatar_id for reuse.\\n\\navatar_id: {look_id}\",\n            cls.hidden.unique_id,\n        )\n        return IO.NodeOutput(look_id, preview)","sourceCodeStart":543,"sourceCodeEnd":579,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_heygen.py#L543-L579","documentation":"Thrown after POSTing to HeyGen's avatar-creation endpoint when the response contains no data.avatar_item.id. As with other HeyGen creation calls, the node needs the returned id to poll the look-training job on _LOOKS_PATH; without it the only recourse is to inspect the raw response embedded in the message.","triggerScenarios":"HeyGen returns an error payload instead of a creation result: invalid prompt (length is pre-validated to 1-1000, so more likely content policy), photo moderation rejection, quota/auth failure, or schema drift in the /v2/avatars response.","commonSituations":"Prompt text trips HeyGen content moderation; account lacks avatar-creation permission/credits; upstream API change renames avatar_item.","solutions":["Inspect the response body in the error message for HeyGen's actual error code","Soften/reword the avatar prompt if moderation is indicated","Verify account credits and avatar-creation access","Retry once — transient 5xx-shaped payloads occasionally surface here"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    await create_avatar(...)\nexcept ValueError as e:\n    if 'did not return an avatar' in str(e):\n        # response body inside the message carries HeyGen's reason (moderation/credits)\n        log_and_surface(str(e))\n        raise","preventionTips":["Keep avatar prompts within policy — content moderation failures surface here","Confirm avatar-creation credits before running batch jobs"],"tags":["heygen","avatar-creation","api-contract","moderation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}