langchain-ai/langchain · error · ValueError

Loading images from 'path' has been removed as of 0.3.15 for

Error message

Loading images from 'path' has been removed as of 0.3.15 for security reasons. Please specify images by 'url'.

What it means

`ImagePromptTemplate.format()` refuses any value for `path` supplied via kwargs or the rendered template. Loading images from local file paths was removed in langchain-core 0.3.15 because it enabled reading arbitrary local files (path traversal / local file exfiltration); images must now be referenced by `url` (which may be a base64 data URL).

Source

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

            ```python
            prompt.format(variable1="foo")
            ```
        """
        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.

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Convert the local file to a base64 data URL and pass it as `url`: `f'data:image/png;base64,{base64.b64encode(open(p,"rb").read()).decode()}'`.
2. Host the image (or use a signed URL / object-storage URL) and pass that as `url`.
3. Remove the `path` key from the template entirely so it cannot render truthy.

Example fix

# before
prompt.format(path='/tmp/cat.png')  # ValueError

# after
import base64
from pathlib import Path
p = Path('/tmp/cat.png')
data_url = 'data:image/png;base64,' + base64.b64encode(p.read_bytes()).decode()
prompt.format(url=data_url)

def to_image_url(source: str) -> str:
    if source.startswith('path:') or (not source.startswith(('http://', 'https://', 'data:'))):
        import base64, pathlib
        p = pathlib.Path(source)
        return 'data:image/png;base64,' + base64.b64encode(p.read_bytes()).decode()
    return source

# usage: prompt.format(url=to_image_url('/tmp/img.png'))

def is_safe_image_reference(value: str) -> bool:
    return isinstance(value, str) and value.startswith(('http://', 'https://', 'data:'))

try:
    out = prompt.format(**vars_)
except ValueError as e:
    if "'path'" in str(e):
        out = prompt.format(url=to_image_url(vars_['path']))
    else:
        raise

When it happens

Trigger: Calling `format(path='/tmp/img.png')`, or having `template={'path': '{img_path}'}` render to a truthy value, on langchain-core >= 0.3.15.

Common situations: Upgrading from langchain-core < 0.3.15 where local-path images worked; multimodal agents that screenshot to disk and attach the file; configs saved with a `path` template key that now fail on load/format.

Related errors

• input_variables for the image template cannot contain any of
• Must provide url.
• url must be a string.
• Only one format variable allowed per image template.\nGot: {
• Invalid image template: {tmpl}

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