microsoft/semantic-kernel · error · RuntimeError

MessageHandlerContext cannot be instantiated. It is a static

Error message

MessageHandlerContext cannot be instantiated. It is a static class that provides context management for message handling.

What it means

MessageHandlerContext is a static class (like AgentInstantiationContext) that provides the current agent ID during message handling via a ContextVar. Its __init__ unconditionally raises RuntimeError. It exposes a classmethod agent_id() and a context manager populate_context() for internal runtime use.

Source

Thrown at python/semantic_kernel/agents/runtime/in_process/message_handler_context.py:18

# Copyright (c) Microsoft. All rights reserved.

from collections.abc import Generator
from contextlib import contextmanager
from contextvars import ContextVar
from typing import Any, ClassVar

from semantic_kernel.agents.runtime.core.agent_id import AgentId
from semantic_kernel.utils.feature_stage_decorator import experimental


@experimental
class MessageHandlerContext:
    """Context for message handlers."""

    def __init__(self) -> None:
        """Instantiate the MessageHandlerContext class."""
        raise RuntimeError(
            "MessageHandlerContext cannot be instantiated. It is a static class that provides context management for "
            "message handling."
        )

    _MESSAGE_HANDLER_CONTEXT: ClassVar[ContextVar[AgentId]] = ContextVar("_MESSAGE_HANDLER_CONTEXT")

    @classmethod
    @contextmanager
    def populate_context(cls, ctx: AgentId) -> Generator[None, Any, None]:
        """Populate the context with the current agent ID."""
        token = MessageHandlerContext._MESSAGE_HANDLER_CONTEXT.set(ctx)
        try:
            yield
        finally:
            MessageHandlerContext._MESSAGE_HANDLER_CONTEXT.reset(token)

    @classmethod
    def agent_id(cls) -> AgentId:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Do not instantiate the class. Use MessageHandlerContext.agent_id() to access the current agent ID from within a message handler.
2. The runtime sets the context automatically when dispatching messages to handlers.

Example fix

# before
ctx = MessageHandlerContext()

# after
agent_id = MessageHandlerContext.agent_id()  # call as classmethod inside a handler

# This is a static class — never instantiate it.
from semantic_kernel.agents.runtime.in_process.message_handler_context import MessageHandlerContext
# Correct: use classmethods directly
agent_id = MessageHandlerContext.agent_id()

null

null

When it happens

Trigger: Calling MessageHandlerContext() directly, e.g. `ctx = MessageHandlerContext()`. The __init__ raises before any state is set.

Common situations: A developer discovers the class and assumes it is a data holder or context object to be instantiated and passed around, rather than a static accessor.

Related errors

• AgentInstantiationContext cannot be instantiated. It is a st
• MessageHandlerContext.agent_id() must be called within a mes
• AgentInstantiationContext.runtime() must be called within an
• AgentInstantiationContext.agent_id() must be called within a
• If agent_type is not specified DefaultSubscription must be c

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/0622b4c383df17b8. Report an issue: GitHub.