microsoft/autogen · error · ValueError

Runtime must be running when sending message.

Error message

Runtime must be running when sending message.

What it means

GrpcWorkerAgentRuntime.send_message (the AgentRuntime RPC entry point) verifies the runtime is running before accepting a directed message; if _running is False it raises ValueError('Runtime must be running when sending message.') because there is no host connection to carry the request.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py:377

        telemetry_metadata: Mapping[str, str],
    ) -> None:
        if self._host_connection is None:
            raise RuntimeError("Host connection is not set.")
        with self._trace_helper.trace_block(send_type, recipient, parent=telemetry_metadata):
            await self._host_connection.send(runtime_message)

    async def send_message(
        self,
        message: Any,
        recipient: AgentId,
        *,
        sender: AgentId | None = None,
        cancellation_token: CancellationToken | None = None,
        message_id: str | None = None,
    ) -> Any:
        # TODO: use message_id
        if not self._running:
            raise ValueError("Runtime must be running when sending message.")
        if self._host_connection is None:
            raise RuntimeError("Host connection is not set.")
        data_type = self._serialization_registry.type_name(message)
        with self._trace_helper.trace_block(
            "create", recipient, parent=None, extraAttributes={"message_type": data_type}
        ):
            # create a new future for the result
            future = asyncio.get_event_loop().create_future()
            request_id = await self._get_new_request_id()
            self._pending_requests[request_id] = future
            serialized_message = self._serialization_registry.serialize(
                message, type_name=data_type, data_content_type=JSON_DATA_CONTENT_TYPE
            )
            telemetry_metadata = get_telemetry_grpc_metadata()
            runtime_message = agent_worker_pb2.Message(
                request=agent_worker_pb2.RpcRequest(
                    request_id=request_id,
                    target=agent_worker_pb2.AgentId(type=recipient.type, key=recipient.key),

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Call and await `runtime.start()` before any send_message / agent call
2. Structure code with an async context manager (`async with runtime: ...`) so start/stop ordering is enforced
3. If a send races shutdown, catch the ValueError and retry once the runtime restarts or drop the message deliberately

Example fix

# before
runtime = GrpcWorkerAgentRuntime(host_address)
await runtime.send_message(msg, agent_id)  # ValueError

# after
runtime = GrpcWorkerAgentRuntime(host_address)
await runtime.start()
await runtime.send_message(msg, agent_id)

started = False
async def ensure_running(runtime):
    global started
    if not started:
        await runtime.start()
        started = True

await ensure_running(runtime)
await runtime.send_message(msg, recipient)

try:
    await runtime.send_message(msg, recipient)
except ValueError as e:
    if "must be running" in str(e):
        await runtime.start()
        await runtime.send_message(msg, recipient)
    else:
        raise

When it happens

Trigger: Calling `await runtime.send_message(msg, recipient)` (or an agent proxy's call) before `await runtime.start()` has completed, or after stop().

Common situations: Forgetting start() in scripts/notebooks; sending during shutdown; agents constructed before the runtime lifecycle begins that send eagerly on instantiation.

Related errors

• Connection is not open.
• Runtime is already running.
• Runtime is not running.
• Host connection is not set.
• Runtime must be running when publishing message.

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