langchain-ai/langchain · error · ValueError

Only one format variable allowed per image template.\nGot: {

Error message

Only one format variable allowed per image template.\nGot: {variables}\nFrom: {tmpl}

What it means

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.

Source

Thrown at libs/core/langchain_core/prompts/chat.py:490

                    <= {
                        "type",
                        "image_url",
                    }
                ):
                    img_template = cast("_ImageTemplateParam", tmpl)["image_url"]
                    input_variables = []
                    if isinstance(img_template, str):
                        variables = get_template_variables(
                            img_template, template_format
                        )
                        if variables:
                            if len(variables) > 1:
                                msg = (
                                    "Only one format variable allowed per image"
                                    f" template.\nGot: {variables}"
                                    f"\nFrom: {tmpl}"
                                )
                                raise ValueError(msg)
                            input_variables = [variables[0]]
                        img_template = {"url": img_template}
                        img_template_obj = ImagePromptTemplate(
                            input_variables=input_variables,
                            template=img_template,
                            template_format=template_format,
                        )
                    elif isinstance(img_template, dict):
                        img_template = dict(img_template)
                        for key in ["url", "path", "detail"]:
                            if key in img_template:
                                input_variables.extend(
                                    get_template_variables(
                                        img_template[key], template_format
                                    )
                                )
                        img_template_obj = ImagePromptTemplate(
                            input_variables=input_variables,

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Reduce the image template to one variable, e.g. 'https://img.example.com/{image_url}' and supply the fully built URL as the value
2. Pre-compose the varying parts upstream (f-string them yourself) so the template contains a single placeholder

Example fix

# before
ChatPromptTemplate.from_messages([
    ("human", [{"type": "image_url", "image_url": "https://cdn/{cat}/{id}.png"}]),
])  # ValueError: two variables

# after
ChatPromptTemplate.from_messages([
    ("human", [{"type": "image_url", "image_url": "{image_url}"}]),
]).invoke({"image_url": f"https://cdn/{cat}/{id}.png"})

from langchain_core.prompts.string import get_template_variables

def valid_image_template(tmpl: str, fmt="f-string") -> bool:
    return len(get_template_variables(tmpl, fmt)) <= 1

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid image template: {tmpl}
• variable {self.variable_name} should be a list of base messa
• Partial variables are not supported for list of templates.
• jinja2 is unsafe and is not supported for templates expresse
• Invalid template: {tmpl}

AI-assisted analysis of langchain-ai/langchain@e32fa9a52e (2026-08-14). Data as JSON: /api/errors/0789f21af2d5e2ae. Report an issue: GitHub.