microsoft/autogen · error · ValueError

Unknown mode: {self.mode}

Error message

Unknown mode: {self.mode}

What it means

ChatCompletionClientRecorder only supports the modes 'record' (capture LLM calls to a session file) and 'replay' (serve cached responses from a session file). Passing any other value for mode reaches the terminal else branch in create() and raises this ValueError.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/experimental/task_centric_memory/utils/chat_completion_client_recorder.py:152

                raise ValueError(error_str)
            self._record_index += 1
            self._num_checked_records += 1

            data = rec.get("response")
            # Populate a CreateResult from the data.
            assert data is not None
            result = CreateResult(
                content=data.get("content", ""),
                finish_reason=data.get("finish_reason", "stop"),
                usage=data.get("usage", RequestUsage(prompt_tokens=0, completion_tokens=0)),
                cached=True,
            )
            return result

        else:
            error_str = f"\nUnknown mode: {self.mode}"
            self.logger.error(error_str)
            raise ValueError(error_str)

    def create_stream(
        self,
        messages: Sequence[LLMMessage],
        *,
        tools: Sequence[Tool | ToolSchema] = [],
        json_output: Optional[bool | type[BaseModel]] = None,
        extra_create_args: Mapping[str, Any] = {},
        cancellation_token: Optional[CancellationToken] = None,
        tool_choice: Tool | Literal["auto", "required", "none"] = "auto",
    ) -> AsyncGenerator[Union[str, CreateResult], None]:
        return self.base_client.create_stream(
            messages,
            tools=tools,
            tool_choice=tool_choice,
            json_output=json_output,
            extra_create_args=extra_create_args,
            cancellation_token=cancellation_token,

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Set mode to exactly "record" or "replay" (lowercase) when constructing the recorder.
2. If mode comes from config, validate it against {"record", "replay"} before constructing the client.

Example fix

# before
recorder = ChatCompletionClientRecorder(client, mode="playback", session_file_path="s.json")
# after
recorder = ChatCompletionClientRecorder(client, mode="replay", session_file_path="s.json")

assert mode in ("record", "replay"), f"mode must be 'record' or 'replay', got {mode!r}"
recorder = ChatCompletionClientRecorder(client, mode=mode, session_file_path=path)

def is_valid_recorder_mode(mode: object) -> bool:
    return isinstance(mode, str) and mode in {"record", "replay"}

When it happens

Trigger: Constructing ChatCompletionClientRecorder with mode set to something other than 'record' or 'replay' (e.g. 'playback', 'Replay' with wrong casing, 'test', or None), then calling create().

Common situations: Typos or casing mistakes in the mode string; passing a mode variable that was never initialized; mode loaded from config/JSON with an unexpected value.

Related errors

• Please set OPENAI_API_KEY environment variable.
• Please set OPENAI_API_KEY environment variable.
• BING_API_KEY environment variable is not set
• Missing MISTRAL_API_KEY environment variable.
• Please set OPENAI_API_KEY environment variable.

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/7324b2a06ca36f14. Report an issue: GitHub.