Comfy-Org/ComfyUI · error · ValueError

Custom aspect ratio is only allowed when multiple images are

Error message

Custom aspect ratio is only allowed when multiple images are connected to the image input.

What it means

Grok image edit constraint: a custom (non-'auto') aspect_ratio is only accepted when multiple images are connected. With exactly one input image the API derives the output aspect from that image, so requesting a custom ratio with n==1 is rejected client-side. Note the interaction with the pro model: pro allows only 1 image, so pro + custom aspect ratio can never pass this check.

Source

Thrown at comfy_api_nodes/nodes_grok.py:449

    @classmethod
    async def execute(
        cls,
        model: str,
        image: Input.Image,
        prompt: str,
        resolution: str,
        number_of_images: int,
        seed: int,
        aspect_ratio: str = "auto",
    ) -> IO.NodeOutput:
        validate_string(prompt, strip_whitespace=True, min_length=1)
        if model == "grok-imagine-image-pro":
            if get_number_of_images(image) > 1:
                raise ValueError("The pro model supports only 1 input image.")
        elif get_number_of_images(image) > 3:
            raise ValueError("A maximum of 3 input images is supported.")
        if aspect_ratio != "auto" and get_number_of_images(image) == 1:
            raise ValueError(
                "Custom aspect ratio is only allowed when multiple images are connected to the image input."
            )
        response = await sync_op(
            cls,
            ApiEndpoint(path="/proxy/xai/v1/images/edits", method="POST"),
            data=ImageEditRequest(
                model=model,
                images=[InputUrlObject(url=f"data:image/png;base64,{tensor_to_base64_string(i)}") for i in image],
                prompt=prompt,
                resolution=resolution.lower(),
                n=number_of_images,
                seed=seed,
                aspect_ratio=None if aspect_ratio == "auto" else aspect_ratio,
            ),
            response_model=ImageGenerationResponse,
        )
        if len(response.data) == 1:
            return IO.NodeOutput(await download_url_to_image_tensor(response.data[0].url))

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Set aspect_ratio back to 'auto' for single-image edits.
2. Connect additional images (up to the model's max) if you truly need a custom aspect ratio.
3. Pre-resize/crop the input image to the target aspect ratio instead of using the node parameter.

Example fix

# before
await grok_image_edit(model='grok-imagine-image', image=img1, aspect_ratio='16:9')  # raises

# after
await grok_image_edit(model='grok-imagine-image', image=img1, aspect_ratio='auto')

if aspect_ratio != "auto":
    assert get_number_of_images(image) > 1, "custom aspect ratio needs multiple input images"

When it happens

Trigger: aspect_ratio != 'auto' AND get_number_of_images(image) == 1 — e.g. single image plus aspect_ratio='16:9'.

Common situations: Users switching from multi-image to single-image edits and leaving the aspect ratio dropdown set; assuming the ratio control is always available; combining the pro model (1 image max) with a custom ratio.

Related errors

• The pro model supports only 1 input image.
• A maximum of 3 input images is supported.
• At least one image is required for editing.
• The {model_id} model supports at most {max_images} input ima
• The prompt references @Image{idx}, but only {total_images} r

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