Comfy-Org/ComfyUI · error · ValueError

Too many reference images: {total_images} (images={len(refer

Error message

Too many reference images: {total_images} (images={len(reference_images)}, image assets={len(reference_image_assets)}). Maximum is {limits['max_images']}.

What it means

Per-model reference limits (seedance2_reference_limits, e.g. 30 images for Seedance 2.5, fewer for other models) are enforced client-side. The count combines direct image inputs plus resolved image assets; exceeding max_images raises with a breakdown of both counts and the cap so the user knows exactly how much to trim.

Source

Thrown at comfy_api_nodes/nodes_bytedance.py:2752

        reference_images = model.get("reference_images", {})
        reference_videos = model.get("reference_videos", {})
        reference_audios = model.get("reference_audios", {})
        reference_assets = model.get("reference_assets", {})

        reference_image_assets, reference_video_assets, reference_audio_assets = await _resolve_reference_assets(
            cls, list(reference_assets.values())
        )

        model_id = SEEDANCE_MODELS[model["model"]]
        limits = seedance2_reference_limits(model_id)

        if not reference_images and not reference_videos and not reference_image_assets and not reference_video_assets:
            if model_id != "dreamina-seedance-2-5-260628" or not (reference_audios or reference_audio_assets):
                raise ValueError("At least one reference image or video or asset is required.")

        total_images = len(reference_images) + len(reference_image_assets)
        if total_images > limits["max_images"]:
            raise ValueError(
                f"Too many reference images: {total_images} "
                f"(images={len(reference_images)}, image assets={len(reference_image_assets)}). "
                f"Maximum is {limits['max_images']}."
            )
        total_videos = len(reference_videos) + len(reference_video_assets)
        if total_videos > limits["max_videos"]:
            raise ValueError(
                f"Too many reference videos: {total_videos} "
                f"(videos={len(reference_videos)}, video assets={len(reference_video_assets)}). "
                f"Maximum is {limits['max_videos']}."
            )
        total_audios = len(reference_audios) + len(reference_audio_assets)
        if total_audios > limits["max_audios"]:
            raise ValueError(
                f"Too many reference audios: {total_audios} "
                f"(audios={len(reference_audios)}, audio assets={len(reference_audio_assets)}). "
                f"Maximum is {limits['max_audios']}."
            )

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Reduce the total number of image references (direct + assets) to at most the stated maximum.
Prefer fewer, stronger reference images since quality does not scale with count.
Check seedance2_reference_limits for the selected model before wiring.

Defensive patterns

Strategy: validation

Validate before calling

from comfy_api_nodes.apis.bytedance import seedance2_reference_limits
total = len(reference_images) + len(reference_image_assets)
assert total <= seedance2_reference_limits(model_id)["max_images"]

Prevention

Look up seedance2_reference_limits for the selected model before wiring references.
Count direct images and asset ids together; both consume the same quota.

When it happens

Trigger: Wiring more reference_images than the cap, or a combination of reference_images and reference_assets entries (each asset dict value counts) whose total exceeds limits["max_images"] for the selected model.

Common situations: Using Autogrow reference inputs with large image batches; mixing uploaded assets and direct images; switching to a model with a lower limit than the workflow was built for.

Related errors

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