langchain-ai/langchain · error · ValueError

jinja2 is unsafe and is not supported for templates expresse

Error message

jinja2 is unsafe and is not supported for templates expressed as dicts. Please use 'f-string' or 'mustache' format.

What it means

from_messages/from_template refuses dict-expressed message templates when template_format='jinja2', raising ValueError. LangChain renders dict templates (DictPromptTemplate) by f-string-style interpolation over the dict contents; doing that with jinja2 would evaluate arbitrary template code over user-influenced data, which is unsafe, so only 'f-string' and 'mustache' are allowed for dict templates.

Source

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

                                    )
                                )
                        img_template_obj = ImagePromptTemplate(
                            input_variables=input_variables,
                            template=img_template,
                            template_format=template_format,
                        )
                    else:
                        msg = f"Invalid image template: {tmpl}"  # type: ignore[unreachable]
                        raise ValueError(msg)
                    prompt.append(img_template_obj)
                elif isinstance(tmpl, dict):
                    if template_format == "jinja2":
                        msg = (
                            "jinja2 is unsafe and is not supported for templates "
                            "expressed as dicts. Please use 'f-string' or 'mustache' "
                            "format."
                        )
                        raise ValueError(msg)
                    data_template_obj = DictPromptTemplate(
                        template=cast("dict[str, Any]", tmpl),
                        template_format=template_format,
                    )
                    prompt.append(data_template_obj)
                else:
                    msg = f"Invalid template: {tmpl}"  # type: ignore[unreachable]
                    raise ValueError(msg)
            return cls(prompt=prompt, **kwargs)
        msg = f"Invalid template: {template}"  # type: ignore[unreachable]
        raise ValueError(msg)

    @classmethod
    def from_template_file(
        cls: type[Self],
        template_file: str | Path,
        input_variables: list[str],
        **kwargs: Any,

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Use template_format='f-string' or 'mustache' for prompts that include dict message templates
2. Keep jinja2 only for pure string templates and express structured messages via tuples/strings instead of raw dicts

Example fix

# before
ChatPromptTemplate.from_messages(
    [("human", [{"type": "text", "text": "{{ q }}"}])],
    template_format="jinja2",  # ValueError
)

# after
ChatPromptTemplate.from_messages(
    [("human", [{"type": "text", "text": "{q}"}])],
    template_format="f-string",
)

def valid_combo(templates, template_format: str) -> bool:
    if template_format == "jinja2" and any(isinstance(t, dict) for t in templates):
        return False
    return True

When it happens

Trigger: Calling ChatPromptTemplate.from_messages([...], template_format='jinja2') where any message element is a dict (e.g. {'type': 'text', 'text': ...}) rather than a plain string.

Common situations: Porting jinja2-based prompts into structured multimodal message lists; teams standardizing on jinja2 house-style then adding image/content-block dicts to the same template.

Related errors

• variable {self.variable_name} should be a list of base messa
• Partial variables are not supported for list of templates.
• Only one format variable allowed per image template.\nGot: {
• Invalid image template: {tmpl}
• Invalid template: {tmpl}

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