{"record":{"id":"20d78baf51a743f9","repo":"calesthio/OpenMontage","slug":"prompt-references-image-max-existing-numbers","errorCode":null,"errorMessage":"prompt references <<<image_{max(existing_numbers)}>>> but only {len(references)} image(s) were provided","messagePattern":"prompt references <<<image_(.+?)>>> but only (.+?) image\\(s\\) were provided","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"tools/_kling/omni.py","lineNumber":32,"sourceCode":") -> tuple[str, list[dict[str, Any]]]:\n    \"\"\"Bind image_list entries to stable Image Omni placeholders.\"\"\"\n\n    references = [\n        {\n            \"index\": index,\n            \"placeholder\": f\"<<<image_{index}>>>\",\n            \"source\": item.get(\"source\") or item.get(\"image\") or item.get(\"image_url\"),\n            \"source_type\": item.get(\"source_type\", \"unknown\"),\n        }\n        for index, item in enumerate(image_list, start=1)\n    ]\n    if not references:\n        return prompt, []\n\n    existing_numbers = [int(value) for value in PLACEHOLDER_RE.findall(prompt)]\n    if existing_numbers:\n        if max(existing_numbers) > len(references):\n            raise ValueError(\n                f\"prompt references <<<image_{max(existing_numbers)}>>> but only {len(references)} image(s) were provided\"\n            )\n        if min(existing_numbers) < 1:\n            raise ValueError(\"Image Omni prompt placeholders must start at <<<image_1>>>\")\n        return prompt, references\n\n    placeholders = \" \".join(item[\"placeholder\"] for item in references)\n    return f\"{prompt}\\nReferences: {placeholders}\", references\n","sourceCodeStart":14,"sourceCodeEnd":41,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/_kling/omni.py#L14-L41","documentation":"Raised by build_image_references()/prompt validation in tools/_kling/omni.py when the prompt already contains <<<image_N>>> placeholders and the largest N exceeds the number of image references supplied. The guard prevents sending a prompt that references an image the backend cannot resolve.","triggerScenarios":"Prompt text contains <<<image_3>>> but only 2 images are passed in image_list; images were removed from the list but the prompt was not updated; index-based prompt written by hand off-by-one.","commonSituations":"Iterating on prompts while adding/removing reference images; LLM generating the prompt with hardcoded placeholder numbers that drift from the actual image count.","solutions":["Add the missing reference image(s) so the count matches the highest placeholder","Or renumber the placeholders down to match the actual image count","Prefer omitting placeholders entirely — the function auto-appends a 'References:' line when no placeholders exist"],"exampleFix":"// before\nprompt, refs = build_image_references('use <<<image_2>>> as the character', images=[img1])\n\n// after\nprompt, refs = build_image_references('use <<<image_2>>> as the character', images=[img1, img2])","handlingStrategy":"validation","validationCode":"import re\n\nPLACEHOLDER_RE = re.compile(r'<<<image_(\\-?\\d+)>>>')\n\ndef placeholders_match_refs(prompt: str, image_count: int) -> bool:\n    nums = [int(n) for n in PLACEHOLDER_RE.findall(prompt)]\n    return not nums or (max(nums) <= image_count and min(nums) >= 1)","typeGuard":null,"tryCatchPattern":"try:\n    prompt, refs = build_image_references(prompt, images)\nexcept ValueError as e:\n    if 'but only' in str(e):\n        # add images or rewrite prompt without high-numbered placeholders\n        raise ValueError(f'reference/prompt mismatch: {len(images)} images vs placeholders in prompt') from e\n    raise","preventionTips":["Generate placeholders programmatically with enumerate(images, start=1) so counts can't drift","Or omit placeholders entirely and let the function append the References line","Re-validate prompts whenever the image list changes"],"tags":["kling","omni","prompt","validation","references"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}