microsoft/autogen · error · InvalidOperationException

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

Error message

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

What it means

Thrown by OpenAIChatRequestMessageConnector.PostProcessMessage when the middleware is running in strict mode and an agent's return message is neither an IMessage<ChatResponseMessage> nor an IMessage<ChatCompletions> envelope. The connector's job is to convert Azure OpenAI SDK response objects into AutoGen messages (TextMessage, ToolCallMessage); in strict mode it refuses to pass through any unrecognized message type. This almost always means the reply was produced by a non-OpenAI agent or an unconverted message flowed into this middleware.

Source

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

                {
                    throw new InvalidOperationException($"Invalid streaming message type {reply.GetType().Name}");
                }
                else
                {
                    yield return reply;
                }
            }
        }
    }

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

    public IMessage? PostProcessStreamingMessage(IMessage<StreamingChatCompletionsUpdate> update, string? currentToolName)
    {
        if (update.Content.ContentUpdate is string contentUpdate)
        {
            // text message
            return new TextMessageUpdate(Role.Assistant, contentUpdate, from: update.From);
        }
        else if (update.Content.FunctionName is string functionName)
        {
            return new ToolCallMessageUpdate(functionName, string.Empty, from: update.From);
        }
        else if (update.Content.FunctionArgumentsUpdate is string functionArgumentsUpdate && currentToolName is string)
        {
            return new ToolCallMessageUpdate(currentToolName, functionArgumentsUpdate, from: update.From);
        }

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Construct the connector with strictMode: false (the default) so unknown message types pass through unchanged
2. Verify the agent wrapped by the connector actually returns Azure.OpenAI ChatResponseMessage/ChatCompletions envelopes
3. If you need strictness, add a converting middleware before this one that maps foreign messages to IMessage<ChatCompletions>
4. Check the actual runtime type of the failing message (message.GetType().Name in the exception) to find which middleware produced it

Example fix

// before
var connector = new OpenAIChatRequestMessageConnector(strictMode: true);
// agent returns plain TextMessage -> InvalidOperationException

// after
var connector = new OpenAIChatRequestMessageConnector(); // strictMode: false, unknown types pass through

// verify before post-processing
bool isConvertible = msg is IMessage<ChatResponseMessage> || msg is IMessage<ChatCompletions>;
if (!isConvertible && connectorStrict) { /* convert or skip */ }

static bool IsOpenAIV1Response(IMessage m) => m is IMessage<ChatResponseMessage> || m is IMessage<ChatCompletions>;

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

When it happens

Trigger: Constructing OpenAIChatRequestMessageConnector(strictMode: true) and letting it post-process a message that is not a MessageEnvelope<ChatResponseMessage> or MessageEnvelope<ChatCompletions> (e.g. a plain TextMessage returned by a custom/inner middleware, or a message from a different provider's agent).

Common situations: Chaining middlewares where a later middleware emits a plain TextMessage; mixing agents from AutoGen.OpenAI.V1 with agents from AutoGen.OpenAI or AutoGen.SemanticKernel in strict pipelines; upgrading samples that assumed lenient passthrough.

Related errors

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

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