microsoft/autogen · critical · RuntimeError

str(message.error)

Error message

str(message.error)

What it means

Not a distinct validation error: this is the propagation point where a GroupChatTermination message carrying an error from any participant or the group chat manager is re-raised as RuntimeError in the consuming coroutine. The original exception (model client failure, agent crash, runtime error) is stringified into message.error, so str(e) shows the underlying cause.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat.py:554

                recipient=AgentId(type=self._group_chat_manager_topic_type, key=self._team_id),
                cancellation_token=cancellation_token,
            )
            # Collect the output messages in order.
            output_messages: List[BaseAgentEvent | BaseChatMessage] = []
            stop_reason: str | None = None

            # Yield the messages until the queue is empty.
            while True:
                message_future = asyncio.ensure_future(self._output_message_queue.get())
                if cancellation_token is not None:
                    cancellation_token.link_future(message_future)
                # Wait for the next message, this will raise an exception if the task is cancelled.
                message = await message_future
                if isinstance(message, GroupChatTermination):
                    # If the message contains an error, we need to raise it here.
                    # This will stop the team and propagate the error.
                    if message.error is not None:
                        raise RuntimeError(str(message.error))
                    stop_reason = message.message.content
                    break
                yield message
                if isinstance(message, ModelClientStreamingChunkEvent):
                    # Skip the model client streaming chunk events.
                    continue
                output_messages.append(message)

            # Yield the final result.
            yield TaskResult(messages=output_messages, stop_reason=stop_reason)

        finally:
            try:
                if shutdown_task is not None:
                    # Wait for the shutdown task to finish.
                    # This will propagate any exceptions raised.
                    await shutdown_task
            finally:

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Read the string inside the RuntimeError — it names the real underlying failure; fix that (API key, model name, network).
2. Wrap runs in try/except RuntimeError and retry transient provider errors (rate limits) with backoff.
3. Validate the model client and run one small smoke-test task before long unattended runs.

Example fix

# before
result = await team.run(task="write a poem")  # RuntimeError: [UnderlyingError ...]

# after
try:
    result = await team.run(task="write a poem")
except RuntimeError as e:
    logger.error("team run failed: %s", e)  # inspect underlying cause in e.args[0]
    raise

try:
    result = await team.run_stream(task=task)
    async for msg in result:
        handle(msg)
except RuntimeError as e:
    logger.exception("team run failed")
    if is_transient(str(e)):  # rate limit / network heuristics
        await asyncio.sleep(backoff())
        retry = True

When it happens

Trigger: Any exception inside a participant agent (e.g. OpenAIChatCompletionClient receiving an invalid API key, rate limit exhaustion, or an agent's on_messages raising) during run()/run_stream(). The error travels through the runtime as GroupChatTermination(error=...) and surfaces here.

Common situations: Invalid or expired LLM API key, network outage to the model provider, token/context-length exceeded, custom agent code raising inside on_messages, or a model client misconfigured (wrong model name).

Related errors

• Invalid chunk type: {type(chunk)}
• Expected Memory, List[Memory], or None, got {type(memory)}
• The model does not support function calling.
• Unsupported tool type: {type(tool)}
• Tool names must be unique: {tool_names}

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