microsoft/semantic-kernel · error · NotSupportedException

Failed to parse the provided audio options from JSON. Ensure

Error message

Failed to parse the provided audio options from JSON. Ensure the JSON structure matches ChatAudioOptions format.

What it means

Thrown inside GetAudioOptions when executionSettings.Audio is a JsonElement and ModelReaderWriter.Read<ChatAudioOptions> either throws or returns null while parsing the JSON. The original exception is wrapped in a NotSupportedException advising the JSON must match the ChatAudioOptions format.

Source

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

    {
        if (executionSettings.Audio is ChatAudioOptions audioOptions)
        {
            return audioOptions;
        }

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

        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);
            }
        }

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Build the audio options as a ChatAudioOptions instance directly instead of JSON.
2. Match the ChatAudioOptions schema in JSON (voice, format, and any required fields for your Azure SDK version).
3. Catch NotSupportedException around settings binding and surface a clear config error.
4. Inspect ex.InnerException (the original parse exception) for the exact schema mismatch.

Example fix

// before (config)
{ "audio": { "voice": "" } }
// throws: Failed to parse the provided audio options from JSON...

// after
#pragma warning disable AOAI001
settings.Audio = new ChatAudioOptions(ChatAudioVoice.Alloy, ChatAudioFormat.Pcm16);
#pragma warning restore AOAI001

ChatAudioOptions? TryParseAudio(JsonElement el)
{
    try { return ModelReaderWriter.Read<ChatAudioOptions>(BinaryData.FromString(el.GetRawText())); }
    catch { return null; }
}

if (settings.Audio is JsonElement a && TryParseAudio(a) is null)
    throw new ArgumentException("Audio JSON does not match ChatAudioOptions schema.");

bool IsParsableAudio(JsonElement el)
{
    try { return ModelReaderWriter.Read<ChatAudioOptions>(BinaryData.FromString(el.GetRawText())) is not null; }
    catch { return false; }
}

try { /* kernel call */ }
catch (NotSupportedException ex) when (ex.Message.Contains("audio options from JSON"))
{ throw new ConfigurationException("Audio options JSON must match ChatAudioOptions format.", ex.InnerException); }

When it happens

Trigger: Setting executionSettings.Audio (from JSON config or deserialized payload) to a JSON token whose shape does not match ChatAudioOptions — e.g. {"audio": {"voice": ""}} missing required fields, or {"audio": "not-an-object"} parsed as a non-object JsonElement, or a payload that ModelReaderWriter cannot bind.

Common situations: Loading audio options from config with wrong field names/structure. Programmatic JSON assembly with incorrect ChatAudioOptions schema. Package version where ChatAudioOptions property names differ from the config.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to parse the provided audio options from string. Ensu
• The provided response modalities JSON array may only contain
• The provided response modalities '{executionSettings.Modalit
• The provided response modalities '{modalityString}' is not s
• The provided response modalities '{responseModalitiesString}

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