{"record":{"id":"0789f21af2d5e2ae","repo":"langchain-ai/langchain","slug":"only-one-format-variable-allowed-per-image-templat","errorCode":null,"errorMessage":"Only one format variable allowed per image template.\\nGot: {variables}\\nFrom: {tmpl}","messagePattern":"Only one format variable allowed per image template\\.\\\\nGot: (.+?)\\\\nFrom: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/core/langchain_core/prompts/chat.py","lineNumber":490,"sourceCode":"                    <= {\n                        \"type\",\n                        \"image_url\",\n                    }\n                ):\n                    img_template = cast(\"_ImageTemplateParam\", tmpl)[\"image_url\"]\n                    input_variables = []\n                    if isinstance(img_template, str):\n                        variables = get_template_variables(\n                            img_template, template_format\n                        )\n                        if variables:\n                            if len(variables) > 1:\n                                msg = (\n                                    \"Only one format variable allowed per image\"\n                                    f\" template.\\nGot: {variables}\"\n                                    f\"\\nFrom: {tmpl}\"\n                                )\n                                raise ValueError(msg)\n                            input_variables = [variables[0]]\n                        img_template = {\"url\": img_template}\n                        img_template_obj = ImagePromptTemplate(\n                            input_variables=input_variables,\n                            template=img_template,\n                            template_format=template_format,\n                        )\n                    elif isinstance(img_template, dict):\n                        img_template = dict(img_template)\n                        for key in [\"url\", \"path\", \"detail\"]:\n                            if key in img_template:\n                                input_variables.extend(\n                                    get_template_variables(\n                                        img_template[key], template_format\n                                    )\n                                )\n                        img_template_obj = ImagePromptTemplate(\n                            input_variables=input_variables,","sourceCodeStart":472,"sourceCodeEnd":508,"githubUrl":"https://github.com/langchain-ai/langchain/blob/e32fa9a52eab3b61ad7a45399bfde59b3e580fc4/libs/core/langchain_core/prompts/chat.py#L472-L508","documentation":"When a message tuple in from_messages/from_template carries ('image', template), and the image template is a string, LangChain extracts format variables from it. An image URL/path template may contain at most one variable (the part that varies); two or more raise ValueError listing the variables found. This mirrors multimodal content blocks where a single image slot takes a single fill-in.","triggerScenarios":"Passing an image template string like 'https://img.example.com/{category}/{id}.png' — two variables — under f-string (default) template_format. A single '{image_path}' is fine; {a}{b} is not.","commonSituations":"Building multimodal prompts from templated CDN URLs or file paths that legitimately have two varying segments, without realizing each image block maps to exactly one variable.","solutions":["Reduce the image template to one variable, e.g. 'https://img.example.com/{image_url}' and supply the fully built URL as the value","Pre-compose the varying parts upstream (f-string them yourself) so the template contains a single placeholder"],"exampleFix":"# before\nChatPromptTemplate.from_messages([\n    (\"human\", [{\"type\": \"image_url\", \"image_url\": \"https://cdn/{cat}/{id}.png\"}]),\n])  # ValueError: two variables\n\n# after\nChatPromptTemplate.from_messages([\n    (\"human\", [{\"type\": \"image_url\", \"image_url\": \"{image_url}\"}]),\n]).invoke({\"image_url\": f\"https://cdn/{cat}/{id}.png\"})","handlingStrategy":"validation","validationCode":"from langchain_core.prompts.string import get_template_variables\n\ndef valid_image_template(tmpl: str, fmt=\"f-string\") -> bool:\n    return len(get_template_variables(tmpl, fmt)) <= 1","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use a single {image_url} placeholder and build full URLs upstream","When templating paths/URLs with multiple varying segments, compose them in code before invoke"],"tags":["prompts","chat","multimodal","images","core"],"backgroundTag":null,"analyzedSha":"e32fa9a52eab3b61ad7a45399bfde59b3e580fc4","analyzedAt":"2026-08-14T18:42:09.092Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}