microsoft/semantic-kernel · error · ArgumentOutOfRangeException

Invalid role: {authorRole}

Error message

Invalid role: {authorRole}

What it means

Thrown by MapBedrockAgentUser when an AuthorRole is neither User nor Assistant. Bedrock's ConversationRole only models User and Assistant, so any other role (System, Tool, Function, custom) cannot be mapped and ArgumentOutOfRangeException is thrown.

Source

Thrown at dotnet/src/Agents/Bedrock/BedrockAgent.cs:596

        {
            Role = this.MapBedrockAgentUser(chatMessageContent.Role),
            Content = [new() { Text = chatMessageContent.Content }]
        };
    }

    private Amazon.BedrockAgentRuntime.ConversationRole MapBedrockAgentUser(AuthorRole authorRole)
    {
        if (authorRole == AuthorRole.User)
        {
            return Amazon.BedrockAgentRuntime.ConversationRole.User;
        }

        if (authorRole == AuthorRole.Assistant)
        {
            return Amazon.BedrockAgentRuntime.ConversationRole.Assistant;
        }

        throw new ArgumentOutOfRangeException($"Invalid role: {authorRole}");
    }

    #endregion
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Filter the message history to only User and Assistant roles before passing to the Bedrock agent.
2. Fold any system instructions into the Bedrock agent's instruction/session configuration instead of a System chat message.
3. Remove or convert Tool/Function role messages to User/Assistant before mapping.

Example fix

// before
var history = new List<ChatMessageContent>
{
    new(AuthorRole.System, "You are helpful."), // -> throws 178
    new(AuthorRole.User, "hi"),
};

// after
var history = new List<ChatMessageContent>
{
    // system prompt configured on the Bedrock agent instead
    new(AuthorRole.User, "hi"),
};

var unsupported = history.Where(m => m.Role != AuthorRole.User && m.Role != AuthorRole.Assistant).ToList();
if (unsupported.Count > 0)
    throw new ArgumentOutOfRangeException($"Bedrock only supports User/Assistant roles; found: {string.Join(", ", unsupported.Select(m => m.Role))}");

static bool HistoryIsBedrockCompatible(IEnumerable<ChatMessageContent> h) =>
    h.All(m => m.Role == AuthorRole.User || m.Role == AuthorRole.Assistant);

try { var role = MapBedrockAgentUser(role); }
catch (ArgumentOutOfRangeException) { /* drop or convert the unsupported-role message */ }

When it happens

Trigger: Message history passed to the Bedrock channel contains a message with Role == AuthorRole.System (or Tool/Function/Custom). MapBedrockAgentUser is invoked for each history message and rejects unsupported roles.

Common situations: Caller forwarded a generic chat history (which commonly starts with a System message) into a Bedrock agent without filtering; tool-call result messages included; multi-provider code reused System prompts verbatim.

Related errors

• Bedrock agents must be invoked with a user message
• The Bedrock agent requires a message to be invoked.
• The streaming configuration must be null for non-streaming r
• The streaming configuration must have StreamFinalResponse se
• Message content cannot be null.

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