run-llama/llama_index · error · ValueError

Unknown mode: {response_mode}

Error message

Unknown mode: {response_mode}

What it means

get_response_synthesizer's factory if/elif chain handles each ResponseMode enum value (COMPACT, TREE_SUMMARIZE, REFINE, SIMPLE_SUMMARIZE, NO_TEXT, CONTEXT_ONLY) and raises ValueError on any other value. The check compares against enum members, so both unknown strings and mistyped/renamed modes land here.

Source

Thrown at llama-index-core/llama_index/core/response_synthesizers/factory.py:198

            output_cls=output_cls,
            streaming=streaming,
            use_async=use_async,
            multimodal=multimodal,
        )
    elif response_mode == ResponseMode.NO_TEXT:
        return NoText(
            callback_manager=callback_manager,
            streaming=streaming,
            multimodal=multimodal,
        )
    elif response_mode == ResponseMode.CONTEXT_ONLY:
        return ContextOnly(
            callback_manager=callback_manager,
            streaming=streaming,
            multimodal=multimodal,
        )
    else:
        raise ValueError(f"Unknown mode: {response_mode}")

View on GitHub (pinned to afd0fef371)

Solutions

1. Use the enum instead of a string: from llama_index.core.response_synthesizers.type import ResponseMode; response_mode=ResponseMode.COMPACT.
2. If using strings, copy the exact member values: 'compact', 'tree_summarize', 'refine', 'simple_summarize', 'no_text', 'context_only'.
3. Validate incoming config against ResponseMode before building the engine: assert mode in [m.value for m in ResponseMode].

Example fix

# before
engine = index.as_query_engine(response_mode="tree_sumarize")  # typo

# after
engine = index.as_query_engine(response_mode="tree_summarize")
# or
from llama_index.core.response_synthesizers.type import ResponseMode
engine = index.as_query_engine(response_mode=ResponseMode.TREE_SUMMARIZE)

from llama_index.core.response_synthesizers.type import ResponseMode
assert response_mode in [m.value for m in ResponseMode], f"bad mode: {response_mode}"

from llama_index.core.response_synthesizers.type import ResponseMode

def is_valid_response_mode(mode) -> bool:
    return mode in ResponseMode or mode in [m.value for m in ResponseMode]

When it happens

Trigger: Passing response_mode as a raw string with a typo ('refnie', 'tree_sumarize'); passing a mode that does not exist in this version ('accumulate' via this factory path where unsupported, or a mode name from newer/older docs); passing an arbitrary string not in ResponseMode.

Common situations: Mode names copied from tutorials of a different llama-index version; config files/CLI flags feeding unchecked strings into as_query_engine(response_mode=...); string constants that drifted from the enum (e.g. 'context_only' vs 'contextonly').

Related errors

• Unable to stream in Accumulate response mode
• Program factory not supported without structured answer filt
• Invalid fusion mode: {self.mode}
• Got empty streaming response
• embed_model must start with str 'local' or of type BaseEmbed

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