{"record":{"id":"dcb080d3a53e8a03","repo":"calesthio/OpenMontage","slug":"model-accepts-at-most-maximum-source-images","errorCode":null,"errorMessage":"{model} accepts at most {maximum} source images","messagePattern":"(.+?) accepts at most (.+?) source images","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"tools/graphics/atlas_image.py","lineNumber":169,"sourceCode":"        elif style == \"x\":\n            payload[\"size\"] = f\"{width}x{height}\"\n        elif style == \"ratio\":\n            payload[\"aspect_ratio\"] = inputs.get(\"aspect_ratio\") or atlas_client.aspect_ratio_from_size(\n                width, height, _COMMON_RATIOS\n            )\n        elif style == \"tier\":\n            payload[\"size\"] = inputs.get(\"resolution\", \"auto\")\n\n        images = list(inputs.get(\"image_urls\") or [])\n        if inputs.get(\"image_url\"):\n            images.insert(0, inputs[\"image_url\"])\n        media_style = spec[\"media_style\"]\n        if media_style == \"images\":\n            maximum = int(spec[\"max_images\"])\n            if not images:\n                raise ValueError(f\"{spec['operation']} requires at least one source image\")\n            if len(images) > maximum:\n                raise ValueError(f\"{model} accepts at most {maximum} source images\")\n            payload[\"images\"] = images\n        elif media_style == \"image\":\n            if len(images) != 1:\n                raise ValueError(\"layer decomposition requires exactly one source image\")\n            payload[\"image\"] = images[0]\n\n        for field in spec.get(\"optional_fields\", ()):\n            if inputs.get(field) is not None:\n                payload[field] = inputs[field]\n        if inputs.get(\"output_format\") and inputs[\"output_format\"] != \"default\":\n            payload[\"output_format\"] = inputs[\"output_format\"]\n\n        extra = inputs.get(\"extra_params\")\n        if isinstance(extra, dict):\n            payload.update(extra)\n        return payload\n\n    @staticmethod","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/graphics/atlas_image.py#L151-L187","documentation":"ValueError raised in _build_payload when the number of source images exceeds the model's max_images limit from its spec. The images list (image_urls, with image_url prepended) is counted after collection, so the single image_url counts toward the same budget as the list entries.","triggerScenarios":"Passing more image_urls than spec['max_images'] for a reference-conditioned model (e.g. 5 refs for a model capped at 4), or combining image_url with an already-full image_urls list so the prepend pushes it over the limit.","commonSituations":"Feeding an entire asset folder as references without checking the cap; mixing the convenience image_url field with image_urls and double-counting; models with different caps used interchangeably in a generic pipeline.","solutions":["Trim image_urls to the model's max_images before the call (keep the most relevant references first).","Do not combine image_url with a full image_urls list — put everything in image_urls.","Read the per-model cap from get_info()'s model catalog and enforce it in your pipeline.","If you need more references than allowed, pick a model family with a higher max_images."],"exampleFix":"# before\ninputs = {\"model\": m, \"image_urls\": refs}  # len(refs)=6 > cap 4 -> ValueError\n\n# after\ncap = tool.get_info()[\"model_catalog\"][m][\"max_images\"]\ninputs = {\"model\": m, \"image_urls\": refs[:cap]}","handlingStrategy":"validation","validationCode":"cap = int(tool.get_info()[\"model_catalog\"][inputs[\"model\"]][\"max_images\"])\nimages = list(inputs.get(\"image_urls\") or [])\nif inputs.get(\"image_url\"):\n    images.insert(0, inputs[\"image_url\"])\nassert len(images) <= cap, f\"{inputs['model']} accepts at most {cap} images\"","typeGuard":"def within_image_cap(tool, model: str, inputs: dict) -> bool:\n    cap = int(tool.get_info()[\"model_catalog\"][model][\"max_images\"])\n    n = len(inputs.get(\"image_urls\") or []) + (1 if inputs.get(\"image_url\") else 0)\n    return n <= cap","tryCatchPattern":"try:\n    result = tool.run(inputs)\nexcept ValueError as e:\n    if \"accepts at most\" in str(e):\n        cap = int(tool.get_info()[\"model_catalog\"][inputs[\"model\"]][\"max_images\"])\n        inputs[\"image_urls\"] = inputs[\"image_urls\"][:cap]\n        inputs.pop(\"image_url\", None)\n        result = tool.run(inputs)\n    else:\n        raise","preventionTips":["Rank references by relevance and slice to the model cap before calling.","Do not mix image_url with a full image_urls list for the same call.","Read max_images from the live catalog rather than trusting remembered values."],"tags":["atlas-cloud","image","input-validation","limits"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}