{"record":{"id":"8f9a335b67fcc866","repo":"microsoft/semantic-kernel","slug":"failed-to-parse-the-provided-audio-options-from-js","errorCode":null,"errorMessage":"Failed to parse the provided audio options from JSON. Ensure the JSON structure matches ChatAudioOptions format.","messagePattern":"Failed to parse the provided audio options from JSON\\. Ensure the JSON structure matches ChatAudioOptions format\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Connectors/Connectors.AzureOpenAI/Core/AzureClientCore.ChatCompletion.cs","lineNumber":244,"sourceCode":"    {\n        if (executionSettings.Audio is ChatAudioOptions audioOptions)\n        {\n            return audioOptions;\n        }\n\n        if (executionSettings.Audio is JsonElement audioOptionsElement)\n        {\n            try\n            {\n                var result = ModelReaderWriter.Read<ChatAudioOptions>(BinaryData.FromString(audioOptionsElement.GetRawText()));\n                if (result != null)\n                {\n                    return result;\n                }\n            }\n            catch (Exception ex)\n            {\n                throw new NotSupportedException(\"Failed to parse the provided audio options from JSON. Ensure the JSON structure matches ChatAudioOptions format.\", ex);\n            }\n        }\n\n        if (executionSettings.Audio is string audioOptionsString)\n        {\n            try\n            {\n                var result = ModelReaderWriter.Read<ChatAudioOptions>(BinaryData.FromString(audioOptionsString));\n                if (result != null)\n                {\n                    return result;\n                }\n            }\n            catch (Exception ex)\n            {\n                throw new NotSupportedException(\"Failed to parse the provided audio options from string. Ensure the string is valid JSON that matches ChatAudioOptions format.\", ex);\n            }\n        }","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Connectors/Connectors.AzureOpenAI/Core/AzureClientCore.ChatCompletion.cs#L226-L262","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Build the audio options as a ChatAudioOptions instance directly instead of JSON.","Match the ChatAudioOptions schema in JSON (voice, format, and any required fields for your Azure SDK version).","Catch NotSupportedException around settings binding and surface a clear config error.","Inspect ex.InnerException (the original parse exception) for the exact schema mismatch."],"exampleFix":"// before (config)\n{ \"audio\": { \"voice\": \"\" } }\n// throws: Failed to parse the provided audio options from JSON...\n\n// after\n#pragma warning disable AOAI001\nsettings.Audio = new ChatAudioOptions(ChatAudioVoice.Alloy, ChatAudioFormat.Pcm16);\n#pragma warning restore AOAI001","handlingStrategy":"validation","validationCode":"ChatAudioOptions? TryParseAudio(JsonElement el)\n{\n    try { return ModelReaderWriter.Read<ChatAudioOptions>(BinaryData.FromString(el.GetRawText())); }\n    catch { return null; }\n}\n\nif (settings.Audio is JsonElement a && TryParseAudio(a) is null)\n    throw new ArgumentException(\"Audio JSON does not match ChatAudioOptions schema.\");","typeGuard":"bool IsParsableAudio(JsonElement el)\n{\n    try { return ModelReaderWriter.Read<ChatAudioOptions>(BinaryData.FromString(el.GetRawText())) is not null; }\n    catch { return false; }\n}","tryCatchPattern":"try { /* kernel call */ }\ncatch (NotSupportedException ex) when (ex.Message.Contains(\"audio options from JSON\"))\n{ throw new ConfigurationException(\"Audio options JSON must match ChatAudioOptions format.\", ex.InnerException); }","preventionTips":["Construct ChatAudioOptions directly when possible.","Match the ChatAudioOptions field schema in config.","Inspect the wrapped inner exception for the exact schema mismatch."],"tags":["azure-openai","execution-settings","audio","json","configuration","csharp"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}