microsoft/semantic-kernel · error · NotSupportedException

Failed to parse the provided audio options from string. Ensu

Error message

Failed to parse the provided audio options from string. Ensure the string is valid JSON that matches ChatAudioOptions format.

What it means

Thrown inside GetAudioOptions when executionSettings.Audio is a string and ModelReaderWriter.Read<ChatAudioOptions> fails to parse it as valid JSON matching the ChatAudioOptions format (throws or returns null). This path is reached only when Audio is a C# string (not a JsonElement).

Source

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

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

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

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Prefer constructing ChatAudioOptions directly rather than round-tripping through a JSON string.
2. If a JSON string is required, ensure it is valid JSON with the correct ChatAudioOptions field names and values.
3. Catch NotSupportedException and inspect ex.InnerException for the parse failure detail.
4. Validate the string parses as JSON before assigning to Audio.

Example fix

// before
settings.Audio = "{\"voice\":\"\"}"; // invalid ChatAudioOptions
// throws: Failed to parse the provided audio options from string...

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

static bool IsValidAudioJsonString(string s)
{
    try { using var doc = JsonDocument.Parse(s); return ModelReaderWriter.Read<ChatAudioOptions>(BinaryData.FromString(s)) is not null; }
    catch { return false; }
}

bool IsParsableAudioString(string s)
{
    try { return ModelReaderWriter.Read<ChatAudioOptions>(BinaryData.FromString(s)) is not null; }
    catch { return false; }
}

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

When it happens

Trigger: Setting executionSettings.Audio = "{\"voice\":\"\"}" or any string that is either not valid JSON or does not conform to ChatAudioOptions. Common when the audio value is read from a flat config string rather than structured JSON.

Common situations: Loading a serialized audio JSON string from environment/config. Passing a malformed or partial JSON string. Schema mismatch with the Azure SDK ChatAudioOptions definition.

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 JSON. Ensure
• 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/8e77433ae159fa0b. Report an issue: GitHub.