What causes "Exactly one input image is required." in Comfy-Org/ComfyUI?

Select a single image from the batch (index/select node) before the Magnific node.

Comfy-Org/ComfyUI · error · ValueError

Exactly one input image is required.

Error message

Exactly one input image is required.

What it means

Raised by the Magnific upscale node (comfy_api_nodes/nodes_magnific.py:166) when the input image batch contains anything other than exactly one image. The Magnific upscaler API processes a single image per request, so batches are rejected before validation of aspect ratio and dimensions.

Source

Thrown at comfy_api_nodes/nodes_magnific.py:166

            ),
        )

    @classmethod
    async def execute(
        cls,
        image: Input.Image,
        prompt: str,
        scale_factor: str,
        optimized_for: str,
        creativity: int,
        hdr: int,
        resemblance: int,
        fractality: int,
        engine: str,
        auto_downscale: bool,
    ) -> IO.NodeOutput:
        if get_number_of_images(image) != 1:
            raise ValueError("Exactly one input image is required.")
        validate_image_aspect_ratio(image, (1, 3), (3, 1), strict=False)
        validate_image_dimensions(image, min_height=160, min_width=160)

        max_output_pixels = 25_300_000
        height, width = get_image_dimensions(image)
        requested_scale = int(scale_factor.rstrip("x"))
        output_pixels = height * width * requested_scale * requested_scale

        if output_pixels > max_output_pixels:
            if auto_downscale:
                # Find optimal scale factor that doesn't require >2x downscale.
                # Server upscales in 2x steps, so aggressive downscaling degrades quality.
                input_pixels = width * height
                scale = 2
                max_input_pixels = max_output_pixels // 4
                for candidate in [16, 8, 4, 2]:
                    if candidate > requested_scale:
                        continue

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Select a single image from the batch (index/select node) before the Magnific node.
Iterate the batch with a loop node, upscaling one image per execution.
Check upstream nodes for unintended batching (e.g. batch load instead of single load).

Example fix

# before
upscaled = await magnific_upscale.execute(image=batch, ...)  # ValueError: batch > 1

# after
single = batch[0:1]  # batch dim 1
upscaled = await magnific_upscale.execute(image=single, ...)

Defensive patterns

Strategy: validation

Validate before calling

if image.shape[0] != 1:
    raise ValueError(f"Magnific expects exactly one image, got batch of {image.shape[0]}")

Prevention

Check tensor.shape[0] on every input to single-image API nodes.
Insert a batch-select node when a workflow mixes batched and single-image consumers.

When it happens

Trigger: Passing a batched image tensor (batch dim != 1) from a batch loader, list-of-images node, or batched upstream operation into the Magnific upscale node's image input.

Common situations: User connects a batch output intending to upscale each frame; batched image nodes earlier in the graph silently propagate batch dims; image lists from preview/split nodes.

Related errors

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