{"record":{"id":"a881a17fc84ec356","repo":"microsoft/semantic-kernel","slug":"channel-keys-must-not-be-empty-unable-to-generate","errorCode":null,"errorMessage":"Channel Keys must not be empty. Unable to generate channel hash.","messagePattern":"Channel Keys must not be empty\\. Unable to generate channel hash\\.","errorType":"exception","errorClass":"AgentExecutionException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/group_chat/agent_chat_utils.py","lineNumber":29,"sourceCode":"@experimental\nclass KeyEncoder:\n    \"\"\"A class for encoding keys.\"\"\"\n\n    @staticmethod\n    def generate_hash(keys: Iterable[str]) -> str:\n        \"\"\"Generate a hash from a list of keys.\n\n        Args:\n            keys: A list of keys to generate the hash from.\n\n        Returns:\n            str: The generated hash.\n\n        Raises:\n            AgentExecutionException: If the keys are empty\n        \"\"\"\n        if not keys:\n            raise AgentExecutionException(\"Channel Keys must not be empty. Unable to generate channel hash.\")\n        joined_keys = \":\".join(keys)\n        buffer = joined_keys.encode(\"utf-8\")\n        sha256_hash = hashlib.sha256(buffer).digest()\n        return base64.b64encode(sha256_hash).decode(\"utf-8\")\n","sourceCodeStart":11,"sourceCodeEnd":34,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/group_chat/agent_chat_utils.py#L11-L34","documentation":"Raised by KeyEncoder.generate_hash() when the keys iterable is empty. The hash is used as a channel-map key derived from an agent's get_channel_keys(); an empty key list means the agent returned no channel keys, making it impossible to generate a unique channel hash. It is an AgentExecutionException.","triggerScenarios":"An Agent subclass whose get_channel_keys() returns an empty list/tuple is added to an AgentGroupChat and invoked. AgentChat._get_agent_hash() calls KeyEncoder.generate_hash(agent.get_channel_keys()), which throws.","commonSituations":"Custom Agent subclass that does not override get_channel_keys() correctly; a bug in an agent factory that produces agents without channel keys; using a mock/stub agent in a group chat that lacks proper channel-key setup.","solutions":["Ensure every Agent subclass returns at least one non-empty string from get_channel_keys().","If using a custom agent, override get_channel_keys() to return [self.__class__.__name__] or another stable identifier.","Validate agents before adding them to the group chat by checking agent.get_channel_keys() is non-empty."],"exampleFix":"# before — custom agent returns empty channel keys\nclass MyAgent(Agent):\n    def get_channel_keys(self) -> list[str]:\n        return []\n\n# after — return at least one stable key\nclass MyAgent(Agent):\n    def get_channel_keys(self) -> list[str]:\n        return [type(self).__name__]","handlingStrategy":"validation","validationCode":"keys = agent.get_channel_keys()\nif not keys:\n    raise ValueError(f\"Agent {agent.name} returned empty channel keys\")\nchat.add_agent(agent)","typeGuard":"def agent_has_channel_keys(agent) -> bool:\n    return bool(agent.get_channel_keys())","tryCatchPattern":null,"preventionTips":["Ensure every Agent subclass overrides get_channel_keys() to return at least one non-empty string.","Validate agents before adding them to AgentGroupChat.","Unit-test custom agent subclasses for non-empty channel keys."],"tags":["validation","channel","group-chat","agent"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}