run-llama/llama_index · error · ValueError

Unsupported mode.

Error message

Unsupported mode.

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/evaluation/retrieval/evaluator.py:103

        for scored_node in retrieved_nodes:
            node = scored_node.node
            if isinstance(node, ImageNode):
                image_nodes.append(node)
            if isinstance(node, TextNode):
                text_nodes.append(node)

        if mode == "text":
            return (
                [node.node_id for node in text_nodes],
                [node.text for node in text_nodes],
            )
        elif mode == "image":
            return (
                [node.node_id for node in image_nodes],
                [node.text for node in image_nodes],
            )
        else:
            raise ValueError("Unsupported mode.")

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass exactly 'text' or 'image' (lowercase strings) as the mode
2. If you hold an enum, pass its value: mode=RetrievalEvalMode.IMAGE.value or str(mode)
3. For multimodal combos, run the evaluator separately per mode instead of inventing new mode strings

Example fix

# before
evaluator.evaluate(..., mode=RetrievalEvalMode.IMAGE)  # enum != 'image' -> raises

# after
evaluator.evaluate(..., mode=RetrievalEvalMode.IMAGE.value)  # 'image'

VALID_MODES = {"text", "image"}
mode = mode if isinstance(mode, str) else getattr(mode, "value", None)
if mode not in VALID_MODES:
    raise ValueError(f"mode must be one of {VALID_MODES}, got {mode!r}")

def is_supported_retrieval_mode(mode: object) -> bool:
    """True when mode is the string 'text' or 'image' (or an enum whose .value is)."""
    value = getattr(mode, "value", mode)
    return isinstance(value, str) and value in {"text", "image"}

When it happens

Trigger: 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'}.

Common situations: 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.

Related errors

• query and response must be provided
• query, contexts, and response must be provided
• Metric key {metric_key} not in results_df
• names and results_arr must have same length.
• query, response, second_response, and reference must be prov

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