{"record":{"id":"c79b08798f65d8f7","repo":"Comfy-Org/ComfyUI","slug":"exactly-one-input-image-is-required","errorCode":null,"errorMessage":"Exactly one input image is required.","messagePattern":"Exactly one input image is required\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_magnific.py","lineNumber":166,"sourceCode":"            ),\n        )\n\n    @classmethod\n    async def execute(\n        cls,\n        image: Input.Image,\n        prompt: str,\n        scale_factor: str,\n        optimized_for: str,\n        creativity: int,\n        hdr: int,\n        resemblance: int,\n        fractality: int,\n        engine: str,\n        auto_downscale: bool,\n    ) -> IO.NodeOutput:\n        if get_number_of_images(image) != 1:\n            raise ValueError(\"Exactly one input image is required.\")\n        validate_image_aspect_ratio(image, (1, 3), (3, 1), strict=False)\n        validate_image_dimensions(image, min_height=160, min_width=160)\n\n        max_output_pixels = 25_300_000\n        height, width = get_image_dimensions(image)\n        requested_scale = int(scale_factor.rstrip(\"x\"))\n        output_pixels = height * width * requested_scale * requested_scale\n\n        if output_pixels > max_output_pixels:\n            if auto_downscale:\n                # Find optimal scale factor that doesn't require >2x downscale.\n                # Server upscales in 2x steps, so aggressive downscaling degrades quality.\n                input_pixels = width * height\n                scale = 2\n                max_input_pixels = max_output_pixels // 4\n                for candidate in [16, 8, 4, 2]:\n                    if candidate > requested_scale:\n                        continue","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_magnific.py#L148-L184","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)."],"exampleFix":"# before\nupscaled = await magnific_upscale.execute(image=batch, ...)  # ValueError: batch > 1\n\n# after\nsingle = batch[0:1]  # batch dim 1\nupscaled = await magnific_upscale.execute(image=single, ...)","handlingStrategy":"validation","validationCode":"if image.shape[0] != 1:\n    raise ValueError(f\"Magnific expects exactly one image, got batch of {image.shape[0]}\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["magnific","upscale","image-batch","input-validation","comfy-api-nodes"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}