calesthio/OpenMontage · error · ValueError

Edit mode requires image_url/image_path or image_urls/image_

Error message

Edit mode requires image_url/image_path or image_urls/image_paths

What it means

ValueError raised while building the x.ai request payload in edit mode. When mode == 'edit', the tool collects a primary image (image_url/image_path) plus extra images (image_urls/image_paths); if the combined list is empty there is nothing to edit and it refuses to call the endpoint.

Source

Thrown at tools/graphics/grok_image.py:195

        extra_images.extend(
            {"url": _file_to_data_uri(path), "type": "image_url"}
            for path in (inputs.get("image_paths") or [])
        )

        if primary_image or extra_images:
            mode = "edit"

        if mode == "edit":
            endpoint = "https://api.x.ai/v1/images/edits"
            if primary_image and not extra_images:
                payload["image"] = primary_image
            else:
                images = []
                if primary_image:
                    images.append(primary_image)
                images.extend(extra_images)
                if not images:
                    raise ValueError(
                        "Edit mode requires image_url/image_path or image_urls/image_paths"
                    )
                payload["images"] = images
        else:
            endpoint = "https://api.x.ai/v1/images/generations"

        return endpoint, payload

    @staticmethod
    def _infer_extension(url: str) -> str:
        suffix = Path(urlparse(url).path).suffix.lower()
        if suffix in {".png", ".jpg", ".jpeg", ".webp"}:
            return suffix
        return ".png"

    @staticmethod
    def _output_paths(output_path: str | None, count: int, extension: str) -> list[Path]:
        if not output_path:

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Provide at least one input image: image_url or image_path (or the plural forms)
2. Check for misspelled input keys in the tool call payload
3. If you actually want a fresh image with no source, set mode to generation instead of edit
4. Log the normalized payload before submit to confirm the image inputs survived your glue code

Example fix

// before
inputs = {"mode": "edit", "prompt": "make the sky sunset-colored"}
// after
inputs = {"mode": "edit", "prompt": "make the sky sunset-colored", "image_path": "photo.png"}

has_image = any(inputs.get(k) for k in ("image_url", "image_path", "image_urls", "image_paths"))
assert not (inputs.get("mode") == "edit" and not has_image), "edit mode needs at least one image input"

When it happens

Trigger: Calling grok_image with mode='edit' (or omitting a prompt so mode is inferred as edit) while providing neither image_url/image_path nor any of image_urls/image_paths. Also when both are None/empty strings/falsy.

Common situations: Agent infers edit mode from the presence of images but the image inputs were dropped from the payload; user typo like image_ur or images_path; conditional logic that only attaches images in the generation branch.

Related errors

• image_to_video requires image_url or image_path
• reference_to_video requires reference_image_urls or referenc
• Input file not found: {path}
• image_list items must include image, image_url, or image_pat
• Input file not found: {path}

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/2d5f54313d85735f. Report an issue: GitHub.