microsoft/autogen · error · InvalidOperationException

Invalid return message type {message.GetType().Name}

Error message

Invalid return message type {message.GetType().Name}

What it means

InvalidOperationException thrown by OpenAIChatRequestMessageConnector.PostProcessMessage (official OpenAI SDK package) when strictMode is true and the agent's return message is not an IMessage<ChatCompletion>. The strict connector only converts full ChatCompletion objects into AutoGen messages; any other return type aborts.

Source

Thrown at dotnet/src/AutoGen.OpenAI/Middleware/OpenAIChatRequestMessageConnector.cs:149

            toolCalls.Add(new ToolCall(currentToolName, currentToolArguments) { ToolCallId = currentToolId });
        }

        if (toolCalls.Any())
        {
            yield return new ToolCallMessage(toolCalls, from: agent.Name)
            {
                Content = text,
            };
        }
    }

    public IMessage PostProcessMessage(IMessage message)
    {
        return message switch
        {
            IMessage<ChatCompletion> m => PostProcessChatCompletions(m),
            _ when strictMode is false => message,
            _ => throw new InvalidOperationException($"Invalid return message type {message.GetType().Name}"),
        };
    }

    private IMessage PostProcessChatCompletions(IMessage<ChatCompletion> message)
    {
        // throw exception if prompt filter results is not null
        if (message.Content.FinishReason == ChatFinishReason.ContentFilter)
        {
            throw new InvalidOperationException("The content is filtered because its potential risk. Please try another input.");
        }

        // throw exception is there is more than on choice
        if (message.Content.Content.Count > 1)
        {
            throw new InvalidOperationException("The content has more than one choice. Please try another input.");
        }

        return PostProcessChatResponseMessage(message.Content, message.From);

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Construct the connector with strictMode: false (default) for passthrough of unknown types
2. Ensure the OpenAIChatAgent's raw ChatCompletion envelopes reach this connector unconverted
3. Use the matching connector package (AutoGen.OpenAI connector for OpenAIChatAgent, .V1 connector for Azure OpenAI agent)

Example fix

// before
var connector = new OpenAIChatRequestMessageConnector(strictMode: true);
// middleware returns TextMessage -> throws

// after
var connector = new OpenAIChatRequestMessageConnector(); // strictMode: false

bool convertible = msg is IMessage<ChatCompletion>;
if (!convertible && strictMode) { /* convert or bypass */ }

static bool IsOpenAICompletionEnvelope(IMessage m) => m is IMessage<ChatCompletion>;

catch (InvalidOperationException ex) when (ex.Message.StartsWith("Invalid return message type")) { /* pass message through without the connector */ }

When it happens

Trigger: An agent wrapped with OpenAIChatRequestMessageConnector(strictMode: true) returns something other than MessageEnvelope<ChatCompletion> — e.g. a pre-converted TextMessage from an earlier middleware or a different SDK's completion type.

Common situations: Middleware ordering issues where conversion happens twice; mixing AutoGen.OpenAI and AutoGen.OpenAI.V1 connectors in one pipeline; strict mode turned on for safety in composed agents.

Related errors

• Invalid return message type {message.GetType().Name}
• Invalid message type: {m.GetType().Name}
• Invalid streaming message type {reply.GetType().Name}
• Invalid message type
• Invalid message type: {m.GetType().Name}

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/58a08b9f742b2983. Report an issue: GitHub.