langchain-ai/langchain · error · ValueError

Must provide url.

Error message

Must provide url.

What it means

`ImagePromptTemplate.format()` requires a url: it takes `kwargs['url']` or the formatted `template['url']`, and if both are missing/empty it raises `ValueError('Must provide url.')`. An `ImageURL` without a url is meaningless, so the constructor of the output payload fails fast.

Source

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

        formatted = {}
        for k, v in self.template.items():
            if isinstance(v, str):
                formatted[k] = DEFAULT_FORMATTER_MAPPING[self.template_format](
                    v, **kwargs
                )
            else:
                formatted[k] = v
        url = kwargs.get("url") or formatted.get("url")
        if kwargs.get("path") or formatted.get("path"):
            msg = (
                "Loading images from 'path' has been removed as of 0.3.15 for security "
                "reasons. Please specify images by 'url'."
            )
            raise ValueError(msg)
        detail = kwargs.get("detail") or formatted.get("detail")
        if not url:
            msg = "Must provide url."
            raise ValueError(msg)
        if not isinstance(url, str):
            msg = "url must be a string."
            raise ValueError(msg)  # noqa: TRY004
        output: ImageURL = {"url": url}
        if detail:
            # Don't check literal values here: let the API check them
            output["detail"] = cast("Literal['auto', 'low', 'high']", detail)
        return output

    async def aformat(self, **kwargs: Any) -> ImageURL:
        """Async format the prompt with the inputs.

        Args:
            **kwargs: Any arguments to be passed to the prompt template.

        Returns:
            A formatted string.
        """

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Pass `url=...` to `format()`.
2. Ensure the template contains a `url` entry (literal or variable) and that every variable is supplied so it renders non-empty.
3. Guard the call: skip/raise early in your own code if the resolved url is falsy.

Example fix

# before
prompt = ImagePromptTemplate(template={'detail': 'low'})
prompt.format()  # ValueError: Must provide url.

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

resolved_url = kwargs.get('url') or template.get('url')
if not resolved_url:
    raise ValueError('Image prompt needs a non-empty url before format().')
out = prompt.format(**kwargs)

def has_image_url(kwargs: dict, template: dict) -> bool:
    return bool(kwargs.get('url') or template.get('url'))

When it happens

Trigger: Calling `format()` with no `url` kwarg while the template either has no `url` key or its `url` entry formats to an empty string; calling `format()` before setting up the url in the template.

Common situations: Template built with only a `detail` or placeholder key; a templated url variable whose value resolves to `''`; refactoring code where the url used to come from `path` (now blocked) and the url branch was never added.

Related errors

• input_variables for the image template cannot contain any of
• 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/bd16a5211c3f742e. Report an issue: GitHub.