{"record":{"id":"a832647e8aa4c084","repo":"Comfy-Org/ComfyUI","slug":"aleph2-supports-at-most-5-keyframes","errorCode":null,"errorMessage":"Aleph2 supports at most 5 keyframes.","messagePattern":"Aleph2 supports at most 5 keyframes\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_runway.py","lineNumber":796,"sourceCode":"        if (keyframes and keyframes.items) and (prompt_images and prompt_images.items):\n            raise ValueError(\"Aleph2 accepts either keyframes or prompt images, not both.\")\n\n        video_duration: float | None = None\n        try:\n            video_duration = video.get_duration()\n        except Exception:\n            video_duration = None\n\n        def _check_seconds(value: float, label: str) -> None:\n            if video_duration is not None and value > video_duration + 0.0001:\n                raise ValueError(f\"{label} {value:.2f}s exceeds the input video duration ({video_duration:.2f}s).\")\n\n        video_url = await upload_video_to_comfyapi(cls, video)\n\n        keyframe_models: list[RunwayAleph2KeyframeSeconds | RunwayAleph2KeyframeAt] = []\n        if keyframes is not None:\n            if len(keyframes.items) > 5:\n                raise ValueError(\"Aleph2 supports at most 5 keyframes.\")\n            for item in keyframes.items:\n                image_url = await upload_image_to_comfyapi(cls, item.image, mime_type=\"image/png\")\n                if item.mode == KEYFRAME_MODE_SECONDS:\n                    _check_seconds(item.value, \"Keyframe timestamp\")\n                    keyframe_models.append(RunwayAleph2KeyframeSeconds(seconds=item.value, uri=image_url))\n                else:\n                    keyframe_models.append(RunwayAleph2KeyframeAt(at=item.value, uri=image_url))\n\n        prompt_image_models: list[RunwayAleph2PromptImage] = []\n        if prompt_images is not None:\n            if len(prompt_images.items) > 5:\n                raise ValueError(\"Aleph2 supports at most 5 prompt images.\")\n            for item in prompt_images.items:\n                image_url = await upload_image_to_comfyapi(cls, item.image, mime_type=\"image/png\")\n                position: RunwayAleph2TimestampPosition | RunwayAleph2RelativePosition\n                if item.mode == PROMPT_IMAGE_MODE_TIMESTAMP:\n                    _check_seconds(item.value, \"Prompt image timestamp\")\n                    position = RunwayAleph2TimestampPosition(timestampSeconds=item.value)","sourceCodeStart":778,"sourceCodeEnd":814,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_runway.py#L778-L814","documentation":"Raised by the Aleph2 node when the keyframes collection contains more than 5 items. The Runway Aleph2 API caps keyframe guidance at 5 images per request, and the node enforces this before uploading any of the keyframe images.","triggerScenarios":"Connecting a keyframes aggregation with 6+ items (each item = one image + timestamp) to the Aleph2 node's keyframes input.","commonSituations":"Dense keyframing workflows that mark every scene change; aggregating multiple RunwayAleph2KeyframeNode outputs into one list.","solutions":["Trim the keyframe list to at most 5 items, keeping the most temporally significant frames","If more coverage is needed, split into two Aleph2 runs over sub-clips"],"exampleFix":"// before\naleph2(prompt, video, keyframes=all_9_keyframes)\n\n// after\naleph2(prompt, video, keyframes=all_9_keyframes[:5])","handlingStrategy":"validation","validationCode":"assert keyframes is None or len(keyframes.items) <= 5, \"Aleph2: at most 5 keyframes\"","typeGuard":"def keyframe_count_ok(keyframes) -> bool:\n    return keyframes is None or len(keyframes.items) <= 5","tryCatchPattern":"try:\n    await aleph2_execute(...)\nexcept ValueError as e:\n    if \"at most 5 keyframes\" in str(e):\n        keyframes.items = keyframes.items[:5]\n        await aleph2_execute(...)\n    else:\n        raise","preventionTips":["Cap keyframe aggregations at 5 upstream of the node","Choose the 5 most distinct poses/scenes rather than consecutive frames"],"tags":["runway","aleph2","keyframes","limit","validation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}