langchain-ai/langchain · error · ValueError

input_variables for the image template cannot contain any of

Error message

input_variables for the image template cannot contain any of 'url', 'path', or 'detail'. Found: {overlap}

What it means

`ImagePromptTemplate.__init__` validates that `input_variables` does not contain `url`, `path`, or `detail`. Those three names are reserved keys of the `ImageURL` output dict that `format()` produces, so declaring them as template variables would make the prompt unrenderable.

Source

Thrown at libs/core/langchain_core/prompts/image.py:58

    def __init__(self, **kwargs: Any) -> None:
        """Create an image prompt template.

        Raises:
            ValueError: If the input variables contain `'url'`, `'path'`, or
                `'detail'`.
        """
        if "input_variables" not in kwargs:
            kwargs["input_variables"] = []

        overlap = set(kwargs["input_variables"]) & {"url", "path", "detail"}
        if overlap:
            msg = (
                "input_variables for the image template cannot contain"
                " any of 'url', 'path', or 'detail'."
                f" Found: {overlap}"
            )
            raise ValueError(msg)

        template = kwargs.get("template", {})
        template_format = kwargs.get("template_format", "f-string")
        for value in template.values():
            if isinstance(value, str):
                get_template_variables(value, template_format)

        super().__init__(**kwargs)

    @property
    def _prompt_type(self) -> str:
        """Return the prompt type key."""
        return "image-prompt"

    @classmethod
    def get_lc_namespace(cls) -> list[str]:
        """Get the namespace of the LangChain object.

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Rename the colliding variable in the template (e.g. `{url}` -> `{image_url}`) and pass `image_url=...` when calling `format`.
2. Pass the url directly via `template={'url': 'https://...'}` (a literal) instead of as a format variable.
3. If you only wanted a detail level, set it as a literal in `template={'detail': 'low'}` rather than a variable.

Example fix

# before
prompt = ImagePromptTemplate(
    input_variables=['url'],
    template={'url': '{url}'},
)

# after
prompt = ImagePromptTemplate(
    input_variables=['image_url'],
    template={'url': '{image_url}'},
)
prompt.format(image_url='https://example.com/cat.png')

RESERVED = {'url', 'path', 'detail'}
vars_ = set(input_variables or [])
if vars_ & RESERVED:
    raise ValueError(f'Rename reserved input variables: {vars_ & RESERVED}')
ImagePromptTemplate(input_variables=input_variables, template=template)

def is_valid_image_input_variables(input_variables: list[str]) -> bool:
    return not (set(input_variables) & {'url', 'path', 'detail'})

When it happens

Trigger: Constructing `ImagePromptTemplate(template={'url': '{url}'})` or passing `input_variables=['url']` (or `path`/`detail`) — any overlap between the declared input variables and the reserved set `{url, path, detail}`.

Common situations: Reusing an old prompt config where `url` was previously an allowed input variable; copy-pasting a text `PromptTemplate` pattern into an image template; migrating code from before the `ImagePromptTemplate` input-variable restrictions.

Related errors

• Must provide url.
• Loading images from 'path' has been removed as of 0.3.15 for
• url must be a string.
• Unsupported source type. Only 'url' and 'base64' are support
• Must provide one of: url, base64, or file_id

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