microsoft/semantic-kernel · error · NotSupportedException

The provided audio options '{executionSettings.Audio?.GetTyp

Error message

The provided audio options '{executionSettings.Audio?.GetType()}' is not supported.

What it means

Thrown by AzureClientCore.GetAudioOptions when the executionSettings.Audio property is set to a type that is neither ChatAudioOptions, a System.Text.Json.JsonElement, nor a string. The method first tries a direct cast, then JSON-element parsing, then string-to-JSON parsing; if none succeed, this NotSupportedException fires. It indicates the caller supplied an audio configuration object in an unrecognized shape.

Source

Thrown at dotnet/src/Connectors/Connectors.AzureOpenAI/Core/AzureClientCore.ChatCompletion.cs:264

        }

        if (executionSettings.Audio is string audioOptionsString)
        {
            try
            {
                var result = ModelReaderWriter.Read<ChatAudioOptions>(BinaryData.FromString(audioOptionsString));
                if (result != null)
                {
                    return result;
                }
            }
            catch (Exception ex)
            {
                throw new NotSupportedException("Failed to parse the provided audio options from string. Ensure the string is valid JSON that matches ChatAudioOptions format.", ex);
            }
        }

        throw new NotSupportedException($"The provided audio options '{executionSettings.Audio?.GetType()}' is not supported.");
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

Set executionSettings.Audio to an instance of ChatAudioOptions directly: executionSettings.Audio = new ChatAudioOptions { Voice = ChatAudioVoice.Alloy, Format = ChatAudioFormat.Wav };
If serializing/deserializing settings through System.Text.Json, ensure the Audio property round-trips as a JsonElement so the JsonElement branch handles it.
If passing a raw JSON string, ensure executionSettings.Audio is assigned a string containing valid JSON matching the ChatAudioOptions schema.
Avoid anonymous types or custom classes for the Audio property; the connector only recognizes ChatAudioOptions, JsonElement, and string.

Example fix

// before — anonymous object is not recognized
executionSettings.Audio = new { voice = "alloy", format = "wav" };

// after — use the SDK type directly
executionSettings.Audio = new ChatAudioOptions
{
    Voice = ChatAudioVoice.Alloy,
    Format = ChatAudioFormat.Wav
};

Defensive patterns

Strategy: validation

Validate before calling

// Validate Audio type before the call
if (executionSettings.Audio is not null
    && executionSettings.Audio is not ChatAudioOptions
    && executionSettings.Audio is not JsonElement
    && executionSettings.Audio is not string)
{
    throw new ArgumentException(
        $"Audio must be ChatAudioOptions, JsonElement, or string, got {executionSettings.Audio.GetType().Name}");
}

Type guard

static bool IsSupportedAudio(object? audio) =>
    audio is null or ChatAudioOptions or JsonElement or string;

Try / catch

try
{
    var result = await kernel.InvokeAsync(chatFunction, arguments);
}
catch (NotSupportedException ex) when (ex.Message.Contains("audio options"))
{
    logger.LogError("Audio options type not supported: {Type}", executionSettings.Audio?.GetType());
    executionSettings.Audio = null; // fallback: disable audio
}

Prevention

Always construct audio options as ChatAudioOptions directly rather than passing intermediate types.
If loading settings from JSON, deserialize into OpenAIPromptExecutionSettings which will produce a JsonElement for Audio.
Avoid anonymous types and custom classes for the Audio property.

When it happens

Trigger: Setting OpenAIPromptExecutionSettings.Audio to any type other than ChatAudioOptions, JsonElement, or string — e.g. an anonymous object, a dictionary, a custom POCO, or a JObject. The throw occurs at the bottom of the method after all three type branches are exhausted.

Common situations: Deserializing execution settings from a configuration source that materializes the Audio property as a non-supported type (e.g. a Dictionary<string,object> or an anonymous type from a JSON parser that is not System.Text.Json). Passing a custom audio options class that looks like ChatAudioOptions but is a different type. Loading settings from a YAML/JSON file whose audio node deserializes to an unexpected CLR type.

Related errors

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