{"record":{"id":"ff9d4c4586668485","repo":"run-llama/llama_index","slug":"unsupported-mode","errorCode":null,"errorMessage":"Unsupported mode.","messagePattern":"Unsupported mode\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/evaluation/retrieval/evaluator.py","lineNumber":103,"sourceCode":"        for scored_node in retrieved_nodes:\n            node = scored_node.node\n            if isinstance(node, ImageNode):\n                image_nodes.append(node)\n            if isinstance(node, TextNode):\n                text_nodes.append(node)\n\n        if mode == \"text\":\n            return (\n                [node.node_id for node in text_nodes],\n                [node.text for node in text_nodes],\n            )\n        elif mode == \"image\":\n            return (\n                [node.node_id for node in image_nodes],\n                [node.text for node in image_nodes],\n            )\n        else:\n            raise ValueError(\"Unsupported mode.\")\n","sourceCodeStart":85,"sourceCodeEnd":104,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/evaluation/retrieval/evaluator.py#L85-L104","documentation":"RetrievalEvaluator's internal node-extraction helper accepts only mode='text' (returning text node ids/texts) or mode='image' (returning image node ids/texts). Any other string raises ValueError('Unsupported mode.') — typically caused by passing a RetrievalEvalMode enum member where its string value is expected (or vice versa) or a typo'd mode.","triggerScenarios":"Calling the evaluator with mode=RetrievalEvalMode.IMAGE (an enum) when the code compares against the string 'image'; passing mode='TEXT' (uppercase) or 'img'; passing a custom mode string not in {'text','image'}.","commonSituations":"Mixing RetrievalEvalMode enum objects and their .value strings across versions; user code introducing new modes like 'audio' not supported by this helper; case-sensitive mode strings from config files.","solutions":["Pass exactly 'text' or 'image' (lowercase strings) as the mode","If you hold an enum, pass its value: mode=RetrievalEvalMode.IMAGE.value or str(mode)","For multimodal combos, run the evaluator separately per mode instead of inventing new mode strings"],"exampleFix":"# before\nevaluator.evaluate(..., mode=RetrievalEvalMode.IMAGE)  # enum != 'image' -> raises\n\n# after\nevaluator.evaluate(..., mode=RetrievalEvalMode.IMAGE.value)  # 'image'","handlingStrategy":"type-guard","validationCode":"VALID_MODES = {\"text\", \"image\"}\nmode = mode if isinstance(mode, str) else getattr(mode, \"value\", None)\nif mode not in VALID_MODES:\n    raise ValueError(f\"mode must be one of {VALID_MODES}, got {mode!r}\")","typeGuard":"def is_supported_retrieval_mode(mode: object) -> bool:\n    \"\"\"True when mode is the string 'text' or 'image' (or an enum whose .value is).\"\"\"\n    value = getattr(mode, \"value\", mode)\n    return isinstance(value, str) and value in {\"text\", \"image\"}","tryCatchPattern":null,"preventionTips":["Normalize enums to their string values before passing mode around","Centralize the allowed-mode set as a constant reused by callers","Add unit tests covering each supported mode string"],"tags":["validation","evaluation","retrieval","enum","mode"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}