microsoft/semantic-kernel · error · ArgumentOutOfRangeException

Invalid role: {role}

Error message

Invalid role: {role}

What it means

BedrockClientUtilities.MapConversationRoleToAuthorRole converts a Bedrock ConversationRole string into a Semantic Kernel AuthorRole. It recognizes only USER, ASSISTANT, and SYSTEM (compared case-insensitively). Any other role string causes an ArgumentOutOfRangeException. This is an internal helper used while translating a Bedrock Converse response back into SK chat content.

Source

Thrown at dotnet/src/Connectors/Connectors.Amazon/Bedrock/Core/BedrockClientUtilities.cs:51

        }
        // Any other status code is considered unset
        return ActivityStatusCode.Unset;
    }

    /// <summary>
    /// Map Conversation role (value) to author role to build message content for semantic kernel output.
    /// </summary>
    /// <param name="role">The ConversationRole in string form to convert to AuthorRole</param>
    /// <returns>The corresponding AuthorRole.</returns>
    /// <exception cref="ArgumentOutOfRangeException">Thrown if invalid role</exception>
    internal static AuthorRole MapConversationRoleToAuthorRole(string role)
    {
        return role.ToUpperInvariant() switch
        {
            "USER" => AuthorRole.User,
            "ASSISTANT" => AuthorRole.Assistant,
            "SYSTEM" => AuthorRole.System,
            _ => throw new ArgumentOutOfRangeException(nameof(role), $"Invalid role: {role}")
        };
    }

    internal static void BedrockServiceClientRequestHandler(object sender, RequestEventArgs e)
    {
        if (e is not WebServiceRequestEventArgs args || !args.Headers.TryGetValue("User-Agent", out string? value) || value.Contains(HttpHeaderConstant.Values.UserAgent))
        {
            return;
        }
        args.Headers["User-Agent"] = $"{value} {HttpHeaderConstant.Values.UserAgent}";
        args.Headers[HttpHeaderConstant.Names.SemanticKernelVersion] = HttpHeaderConstant.Values.GetAssemblyVersion(typeof(BedrockClientUtilities));
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Upgrade the Microsoft.SemanticKernel.Connectors.Amazon package to a version that recognizes the role AWS is returning.
2. If the role comes from content you control, normalize the ConversationRole to user/assistant/system before it reaches the connector.
3. Wrap the high-level chat completion call (kernel.InvokePromptAsync / IChatCompletionService) in try/catch and surface the raw role for diagnosis.

try
{
    var response = await bedrockChatCompletion.GetChatMessageContentAsync(chatHistory, settings, cancellationToken);
}
catch (ArgumentOutOfRangeException ex) when (ex.Message.Contains("Invalid role"))
{
    // The Bedrock response contained a role the connector does not recognize.
    // Upgrade Connectors.Amazon, or inspect the raw Converse response for the new role.
    logger.LogError(ex, "Unrecognized Bedrock role in response. Upgrade the connector.");
    throw;
}

When it happens

Trigger: A Bedrock Converse API response returns a Message whose Role is something other than user/assistant/system (e.g. a newly introduced role, or an unexpected/tool role). The connector then calls MapConversationRoleToAuthorRole on that role string and throws.

Common situations: AWS adds a new ConversationRole value the installed connector version does not yet know. A custom/patched model response returns a non-standard role. Using an outdated Connectors.Amazon package against newer Bedrock response shapes.

Related errors

• Invalid role: {role}
• Last message in chat history was null or whitespace.
• Unsupported AI21 model: {modelId}
• Unsupported Amazon model: {modelId}
• Unsupported Anthropic model: {modelId}

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