microsoft/autogen · error · InvalidOperationException

Failed to clone options

Error message

Failed to clone options

What it means

OpenAIChatAgent clones its stored ChatCompletionsOptions on every call by round-tripping through System.Text.Json. If JsonSerializer.Deserialize returns null (options became null mid-flight or serialization produced 'null'), it throws InvalidOperationException to avoid mutating the shared original.

Source

Thrown at dotnet/src/AutoGen.OpenAI.V1/Agent/OpenAIChatAgent.cs:140

    }

    private ChatCompletionsOptions CreateChatCompletionsOptions(GenerateReplyOptions? options, IEnumerable<IMessage> messages)
    {
        var oaiMessages = messages.Select(m => m switch
        {
            IMessage<ChatRequestMessage> chatRequestMessage => chatRequestMessage.Content,
            _ => throw new ArgumentException("Invalid message type")
        });

        // add system message if there's no system message in messages
        if (!oaiMessages.Any(m => m is ChatRequestSystemMessage))
        {
            oaiMessages = new[] { new ChatRequestSystemMessage(systemMessage) }.Concat(oaiMessages);
        }

        // clone the options by serializing and deserializing
        var json = JsonSerializer.Serialize(this.options);
        var settings = JsonSerializer.Deserialize<ChatCompletionsOptions>(json) ?? throw new InvalidOperationException("Failed to clone options");

        foreach (var m in oaiMessages)
        {
            settings.Messages.Add(m);
        }

        settings.Temperature = options?.Temperature ?? settings.Temperature;
        settings.MaxTokens = options?.MaxToken ?? settings.MaxTokens;

        foreach (var functions in this.options.Tools)
        {
            settings.Tools.Add(functions);
        }

        foreach (var stopSequence in this.options.StopSequences)
        {
            settings.StopSequences.Add(stopSequence);
        }

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Do not mutate or null out the agent's options after construction; treat the agent as immutable
2. Pin matching versions of the OpenAI .NET SDK and AutoGen.OpenAI.V1
3. If you need per-call settings, pass them via GenerateReplyOptions instead of rewriting this.options

catch (InvalidOperationException ex) when (ex.Message == "Failed to clone options")
{
    logger.LogCritical(ex, "Agent options corrupted; recreating agent");
    agent = BuildAgent(); // reconstruct with fresh options
}

When it happens

Trigger: The agent's options instance was set to null after construction, or a custom JsonSerializerContext/converters caused Serialize(options) to emit "null"; the clone step then fails on every request.

Common situations: Rare in practice; seen when the options field is mutated by user code via reflection or partial classes, or with SDK version mismatches where ChatCompletionsOptions lost a parameterless serialization shape.

Related errors

• Failed to fetch galleries
• Failed to fetch gallery
• Please set OPENAI_API_KEY environment variable.
• Please set OPENAI_API_KEY environment variable.
• Please set OPENAI_API_KEY environment variable.

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