calesthio/OpenMontage · error · ValueError

layer decomposition requires exactly one source image

Error message

layer decomposition requires exactly one source image

What it means

ValueError raised in _build_payload for single-image ('image' media_style) models — the layer decomposition operation — when the collected images list does not contain exactly one entry. It fires both for zero images and for two or more, since payload['image'] takes a single URL.

Source

Thrown at tools/graphics/atlas_image.py:173

                width, height, _COMMON_RATIOS
            )
        elif style == "tier":
            payload["size"] = inputs.get("resolution", "auto")

        images = list(inputs.get("image_urls") or [])
        if inputs.get("image_url"):
            images.insert(0, inputs["image_url"])
        media_style = spec["media_style"]
        if media_style == "images":
            maximum = int(spec["max_images"])
            if not images:
                raise ValueError(f"{spec['operation']} requires at least one source image")
            if len(images) > maximum:
                raise ValueError(f"{model} accepts at most {maximum} source images")
            payload["images"] = images
        elif media_style == "image":
            if len(images) != 1:
                raise ValueError("layer decomposition requires exactly one source image")
            payload["image"] = images[0]

        for field in spec.get("optional_fields", ()):
            if inputs.get(field) is not None:
                payload[field] = inputs[field]
        if inputs.get("output_format") and inputs["output_format"] != "default":
            payload["output_format"] = inputs["output_format"]

        extra = inputs.get("extra_params")
        if isinstance(extra, dict):
            payload.update(extra)
        return payload

    @staticmethod
    def _upload_value(value: str, api_key: str) -> str:
        return value if _is_remote(value) else atlas_client.upload_media(value, api_key)

    def _resolve_media(self, inputs: dict[str, Any], api_key: str) -> dict[str, Any]:

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Pass exactly one image: either image_url='...' alone or image_urls=[single_url].
2. Normalize your pipeline to one canonical field and drop the other before calling single-image operations.
3. Validate `len(images) == 1` upstream with a clear error if callers may supply arrays.
4. For multi-image needs use a model whose media_style is 'images', not the decomposition model.

Example fix

# before
inputs = {"model": m, "image_urls": [front, back]}  # decomposition -> ValueError

# after
inputs = {"model": m, "image_url": front}  # exactly one source image

images = list(inputs.get("image_urls") or [])
if inputs.get("image_url"):
    images.insert(0, inputs["image_url"])
assert len(images) == 1, "layer decomposition needs exactly one source image"

def exactly_one_image(inputs: dict) -> bool:
    n = len(inputs.get("image_urls") or []) + (1 if inputs.get("image_url") else 0)
    return n == 1

try:
    result = tool.run(inputs)
except ValueError as e:
    if "exactly one source image" in str(e):
        result = tool.run({**inputs, "image_url": inputs["image_urls"][0], "image_urls": None})
    else:
        raise

When it happens

Trigger: Calling layer decomposition with an empty images list (no image_url/image_urls), or passing multiple URLs (e.g. image_url plus a non-empty image_urls list) when the operation accepts exactly one.

Common situations: Generic wrappers that always pass image_urls arrays hitting a single-image endpoint; combining the singular and plural fields; forgetting the input image for a decomposition request.

Related errors

• {spec['operation']} requires at least one source image
• {model} accepts at most {maximum} source images
• Unsupported Atlas image model id {model!r}. Use get_info()['
• {family} does not expose generation_mode={operation!r} on At
• unknown project: {project_id}

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