{"record":{"id":"b51efc2af7e5e391","repo":"run-llama/llama_index","slug":"a-retrieved-image-must-have-image-path-or-image-ur","errorCode":null,"errorMessage":"A retrieved image must have image_path or image_url specified.","messagePattern":"A retrieved image must have image_path or image_url specified\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/response/notebook_utils.py","lineNumber":133,"sourceCode":"        image_nodes = response.metadata[\"image_nodes\"] or []\n    else:\n        image_nodes = []\n    num_subplots = len(image_nodes)\n\n    f, axarr = plt.subplots(1, num_subplots)\n    f.set_figheight(plot_height)\n    f.set_figwidth(plot_width)\n    ix = 0\n    for ix, scored_img_node in enumerate(image_nodes):\n        img_node = scored_img_node.node\n        image = None\n        if img_node.image_url:\n            img_response = requests.get(img_node.image_url, timeout=(60, 60))\n            image = Image.open(BytesIO(img_response.content)).convert(\"RGB\")\n        elif img_node.image_path:\n            image = Image.open(img_node.image_path).convert(\"RGB\")\n        else:\n            raise ValueError(\n                \"A retrieved image must have image_path or image_url specified.\"\n            )\n        if num_subplots > 1:\n            axarr[ix].imshow(image)\n            axarr[ix].set_title(f\"Retrieved Position: {ix}\", pad=10, fontsize=9)\n        else:\n            axarr.imshow(image)\n            axarr.set_title(f\"Retrieved Position: {ix}\", pad=10, fontsize=9)\n\n    f.tight_layout()\n    print(f\"Query: {query_str}\\n=======\")\n    print(f\"Retrieved Images:\\n\")\n    plt.show()\n    print(\"=======\")\n    print(f\"Response: {response.response}\\n=======\\n\")\n","sourceCodeStart":115,"sourceCodeEnd":149,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/response/notebook_utils.py#L115-L149","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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)).","Filter before display: skip or guard nodes lacking both attributes instead of passing every node to the utility.","If the node only has metadata (e.g. metadata['image_path']), construct an ImageNode from it or set node.image_path before rendering.","For remote images, confirm image_url is reachable (it is fetched with requests.get)."],"exampleFix":"# before\nfor sn in image_nodes:\n    display_source_node(sn)  # raises if node has no image_path/image_url\n\n# after\nfrom llama_index.core.schema import ImageNode\nrenderable = [sn for sn in image_nodes\n              if isinstance(sn.node, ImageNode) and (sn.node.image_path or sn.node.image_url)]\nfor sn in renderable:\n    display_source_node(sn)","handlingStrategy":"type-guard","validationCode":"from llama_index.core.schema import ImageNode\nrenderable = [s for s in image_nodes\n              if isinstance(s.node, ImageNode) and (s.node.image_path or s.node.image_url)]","typeGuard":"from llama_index.core.schema import ImageNode\n\ndef has_renderable_image(node) -> bool:\n    return isinstance(node, ImageNode) and bool(node.image_path or node.image_url)","tryCatchPattern":"for sn in image_nodes:\n    try:\n        display_source_node(sn, img_source_key=\"image\")\n    except ValueError:\n        continue  # node carries no image","preventionTips":["Create ImageNode(image_path=...) at ingestion so path survives into retrieval.","Filter nodes by image capability before calling display utilities."],"tags":["multimodal","images","notebook","retrieval"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}