run-llama/llama_index · error · ValueError

Unknown chat mode: {chat_mode}

Error message

Unknown chat mode: {chat_mode}

What it means

as_chat_engine dispatches on the chat_mode enum and falls through to ValueError(f"Unknown chat mode: {chat_mode}") when the value matches none of the supported branches (CONDENSE_QUESTION, CONDENSE_PLUS_CONTEXT, SIMPLE, CONTEXT, etc. — and the removed REACT/OPENAI are caught earlier with their own message). Note the message uses literal {chat_mode} formatting only if f-string interpolation is bypassed; normally the actual value appears.

Source

Thrown at llama-index-core/llama_index/core/indices/base.py:591

        elif chat_mode in [ChatMode.CONDENSE_PLUS_CONTEXT, ChatMode.BEST]:
            from llama_index.core.chat_engine import CondensePlusContextChatEngine

            return CondensePlusContextChatEngine.from_defaults(
                retriever=self.as_retriever(**kwargs),
                llm=llm,
                **kwargs,
            )

        elif chat_mode == ChatMode.SIMPLE:
            from llama_index.core.chat_engine import SimpleChatEngine

            return SimpleChatEngine.from_defaults(
                llm=llm,
                **kwargs,
            )
        else:
            raise ValueError(f"Unknown chat mode: {chat_mode}")


# legacy
BaseGPTIndex = BaseIndex

View on GitHub (pinned to afd0fef371)

Solutions

1. Import the enum and use its members: from llama_index.core.chat_engine import ChatMode; chat_mode=ChatMode.CONDENSE_QUESTION.
2. Check the ChatMode enum definition for your installed version to see available modes.
3. If you intended an agent-style chat, migrate to agent.workflow classes (see error 167).
4. Omit chat_mode entirely to use the default (CONDENSE_QUESTION).

Example fix

# before
engine = index.as_chat_engine(chat_mode="condense")  # Unknown chat mode

# after
from llama_index.core.chat_engine import ChatMode
engine = index.as_chat_engine(chat_mode=ChatMode.CONDENSE_QUESTION)

from llama_index.core.chat_engine import ChatMode
valid = set(ChatMode)
if chat_mode not in valid:
    raise ValueError(f"chat_mode must be one of {sorted(m.name for m in valid)}")

def is_valid_chat_mode(mode) -> bool:
    from llama_index.core.chat_engine import ChatMode
    return mode in set(ChatMode)

try:
    engine = index.as_chat_engine(chat_mode=chat_mode)
except ValueError as e:
    if "Unknown chat mode" in str(e):
        engine = index.as_chat_engine()  # fall back to default mode
    else:
        raise

When it happens

Trigger: Passing an invalid string like chat_mode='condense' (the enum member name is CONDENSE_QUESTION); passing a stale enum value removed in an upgrade; passing a value from a different library's ChatMode enum.

Common situations: Typos or wrong casing in chat_mode strings; mixing ChatMode enums from different llama-index module paths across versions; hallucinated mode names copied from outdated snippets.

Related errors

• Cannot specify both system_prompt and prefix_messages
• Cannot specify both system_prompt and prefix_messages
• Unsupported mode.
• Unknown retriever mode: {retriever_mode}
• Unknown query mode: {query_mode}

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