run-llama/llama_index · error · ValueError

A retrieved image must have image_path or image_url specifie

Error message

A retrieved image must have image_path or image_url specified.

What it means

In display_source_node / display_query_sources (notebook image rendering), each retrieved node must carry either image_url or image_path so the image can be fetched and opened. The ValueError fires when an ImageNode has both attributes unset. Note image_url is checked first and downloaded via requests with a 60s timeout, then image_path is opened locally.

Source

Thrown at llama-index-core/llama_index/core/response/notebook_utils.py:133

        image_nodes = response.metadata["image_nodes"] or []
    else:
        image_nodes = []
    num_subplots = len(image_nodes)

    f, axarr = plt.subplots(1, num_subplots)
    f.set_figheight(plot_height)
    f.set_figwidth(plot_width)
    ix = 0
    for ix, scored_img_node in enumerate(image_nodes):
        img_node = scored_img_node.node
        image = None
        if img_node.image_url:
            img_response = requests.get(img_node.image_url, timeout=(60, 60))
            image = Image.open(BytesIO(img_response.content)).convert("RGB")
        elif img_node.image_path:
            image = Image.open(img_node.image_path).convert("RGB")
        else:
            raise ValueError(
                "A retrieved image must have image_path or image_url specified."
            )
        if num_subplots > 1:
            axarr[ix].imshow(image)
            axarr[ix].set_title(f"Retrieved Position: {ix}", pad=10, fontsize=9)
        else:
            axarr.imshow(image)
            axarr.set_title(f"Retrieved Position: {ix}", pad=10, fontsize=9)

    f.tight_layout()
    print(f"Query: {query_str}\n=======")
    print(f"Retrieved Images:\n")
    plt.show()
    print("=======")
    print(f"Response: {response.response}\n=======\n")

View on GitHub (pinned to afd0fef371)

Solutions

1. Ensure retrieved nodes are ImageNode instances with image_path (local file) or image_url set at ingestion time, e.g. ImageNode(image_path=str(p)).
2. Filter before display: skip or guard nodes lacking both attributes instead of passing every node to the utility.
3. If the node only has metadata (e.g. metadata['image_path']), construct an ImageNode from it or set node.image_path before rendering.
4. For remote images, confirm image_url is reachable (it is fetched with requests.get).

Example fix

# before
for sn in image_nodes:
    display_source_node(sn)  # raises if node has no image_path/image_url

# after
from llama_index.core.schema import ImageNode
renderable = [sn for sn in image_nodes
              if isinstance(sn.node, ImageNode) and (sn.node.image_path or sn.node.image_url)]
for sn in renderable:
    display_source_node(sn)

from llama_index.core.schema import ImageNode
renderable = [s for s in image_nodes
              if isinstance(s.node, ImageNode) and (s.node.image_path or s.node.image_url)]

from llama_index.core.schema import ImageNode

def has_renderable_image(node) -> bool:
    return isinstance(node, ImageNode) and bool(node.image_path or node.image_url)

for sn in image_nodes:
    try:
        display_source_node(sn, img_source_key="image")
    except ValueError:
        continue  # node carries no image

When it happens

Trigger: Retrieving plain TextNodes (no image metadata) and passing them to the image display utility; building ImageNode(text=...) without setting image_path; ingesting images without storing their paths in node metadata so image_path never gets populated at retrieval time.

Common situations: Using a multimodal RAG demo where metadata mapping nodes back to source images was dropped during chunking or indexing; multi-modal index built with default text pipeline; renaming/moving image files after indexing so paths exist as keys but were never set.

Related errors

• No image found in node.
• The specified file path is not an accessible image
• The specified URL is not an accessible image
• No image found in the chat message!
• LLM only supports text inputs

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/b51efc2af7e5e391. Report an issue: GitHub.