{"record":{"id":"0b7b6af7e9c28e9f","repo":"microsoft/semantic-kernel","slug":"unsupported-role-message-role-label-only-system","errorCode":null,"errorMessage":"Unsupported role {message.Role.Label}. Only system, user, developer or assistant roles are allowed.","messagePattern":"Unsupported role (.+?)\\. Only system, user, developer or assistant roles are allowed\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Agents/OpenAI/Extensions/ChatContentMessageExtensions.cs","lineNumber":54,"sourceCode":"        return messages.Select(message => message.ToThreadInitializationMessage());\n    }\n\n    /// <summary>\n    /// Converts a <see cref=\"ChatMessageContent\"/> instance to a <see cref=\"ResponseItem\"/>.\n    /// </summary>\n    /// <param name=\"message\">The chat message content to convert.</param>\n    /// <returns>A <see cref=\"ResponseItem\"/> instance.</returns>\n    public static ResponseItem ToResponseItem(this ChatMessageContent message)\n    {\n        var items = message.Items;\n        IEnumerable<ResponseContentPart> contentParts = items.Select(item => item.ToResponseContentPart());\n        return message.Role.Label.ToUpperInvariant() switch\n        {\n            \"SYSTEM\" => ResponseItem.CreateSystemMessageItem(contentParts),\n            \"USER\" => ResponseItem.CreateUserMessageItem(contentParts),\n            \"DEVELOPER\" => ResponseItem.CreateDeveloperMessageItem(contentParts),\n            \"ASSISTANT\" => ResponseItem.CreateAssistantMessageItem(contentParts),\n            _ => throw new NotSupportedException($\"Unsupported role {message.Role.Label}. Only system, user, developer or assistant roles are allowed.\"),\n        };\n    }\n}\n","sourceCodeStart":36,"sourceCodeEnd":58,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Agents/OpenAI/Extensions/ChatContentMessageExtensions.cs#L36-L58","documentation":"ChatContentMessageExtensions.ToResponseItem converts a ChatMessageContent into an OpenAI Responses-API ResponseItem. It only recognizes the SYSTEM, USER, DEVELOPER, and ASSISTANT role labels; any other role throws NotSupportedException.","triggerScenarios":"Passing a ChatMessageContent whose Role is Tool (or a custom AuthorRole) into the Responses-API conversion path used by OpenAIResponseAgent.","commonSituations":"Feeding a tool-result message or function-call content into a Responses-API agent that only accepts the four conversational roles; mixing Assistant-API message shapes with the Responses converter.","solutions":["Filter the chat history to only system/user/developer/assistant messages before sending to a Responses-API agent.","Convert tool-result messages into a user-role message (text) when the Responses API requires it.","Use the correct agent type (OpenAIAssistantAgent vs OpenAIResponseAgent) for your message stream.","Log message.Role.Label before conversion to detect unsupported roles."],"exampleFix":"// before\nvar items = history.Select(m => m.ToResponseItem());\n// after\nvar allowed = new[] { \"SYSTEM\", \"USER\", \"DEVELOPER\", \"ASSISTANT\" };\nvar items = history\n    .Where(m => allowed.Contains(m.Role.Label.ToUpperInvariant()))\n    .Select(m => m.ToResponseItem());","handlingStrategy":"type-guard","validationCode":"var allowed = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { \"system\", \"user\", \"developer\", \"assistant\" };\nif (!allowed.Contains(message.Role.Label))\n    throw new ArgumentException($\"Role '{message.Role.Label}' cannot be converted to a ResponseItem.\");","typeGuard":"static bool IsSupportedResponseRole(ChatMessageContent m) =>\n    m.Role.Label.ToUpperInvariant() is \"SYSTEM\" or \"USER\" or \"DEVELOPER\" or \"ASSISTANT\";","tryCatchPattern":"try { var item = message.ToResponseItem(); }\ncatch (NotSupportedException ex) when (ex.Message.Contains(\"Unsupported role\")) {\n    // map tool/other messages to a user message, or drop them\n}","preventionTips":["Filter history to supported roles before sending to a Responses-API agent.","Keep a shared allow-list of roles for the converter.","Avoid passing tool messages into Responses-API paths."],"tags":["openai","responses-api","message-role","invalid-argument"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}