{"record":{"id":"ec720c52057a17d7","repo":"microsoft/semantic-kernel","slug":"the-format-format-is-not-supported","errorCode":null,"errorMessage":"The format '{format}' is not supported.","messagePattern":"The format '(.+?)' is not supported\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Connectors/Connectors.OpenAI/Core/ClientCore.TextToAudio.cs","lineNumber":71,"sourceCode":"            \"FABLE\" => GeneratedSpeechVoice.Fable,\n            \"ONYX\" => GeneratedSpeechVoice.Onyx,\n            \"NOVA\" => GeneratedSpeechVoice.Nova,\n            \"SHIMMER\" => GeneratedSpeechVoice.Shimmer,\n            _ => throw new NotSupportedException($\"The voice '{voice}' is not supported.\"),\n        };\n\n    private static (GeneratedSpeechFormat? Format, string? MimeType) GetGeneratedSpeechFormatAndMimeType(string? format)\n    {\n        switch (format?.ToUpperInvariant())\n        {\n            case \"WAV\": return (GeneratedSpeechFormat.Wav, \"audio/wav\");\n            case \"MP3\": return (GeneratedSpeechFormat.Mp3, \"audio/mpeg\");\n            case \"OPUS\": return (GeneratedSpeechFormat.Opus, \"audio/opus\");\n            case \"FLAC\": return (GeneratedSpeechFormat.Flac, \"audio/flac\");\n            case \"AAC\": return (GeneratedSpeechFormat.Aac, \"audio/aac\");\n            case \"PCM\": return (GeneratedSpeechFormat.Pcm, \"audio/l16\");\n            case null: return (null, null);\n            default: throw new NotSupportedException($\"The format '{format}' is not supported.\");\n        }\n    }\n}\n","sourceCodeStart":53,"sourceCodeEnd":75,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Connectors/Connectors.OpenAI/Core/ClientCore.TextToAudio.cs#L53-L75","documentation":"The audio output format string is matched case-insensitively against a fixed set (WAV, MP3, OPUS, FLAC, AAC, PCM). A null format is allowed (returns nulls, letting the API pick its default), but any non-null unrecognized string throws NotSupportedException. This check runs before the HTTP request is made.","triggerScenarios":"Passing OpenAITextToAudioExecutionSettings.GeneratedSpeechFormat (or equivalent) a value like 'ogg', 'webm', or a MIME-type string such as 'audio/mpeg' that does not match the allowed tokens.","commonSituations":"Confusing the format token with a MIME type or file extension (e.g. 'mp3 ' vs 'mp3'). Requesting a format the connector version doesn't map. Copying a format value from a different SDK's docs.","solutions":["Use one of: wav, mp3, opus, flac, aac, pcm (case-insensitive).","Leave the format unset/null to let the API use its default if you don't need a specific container.","If you need a format outside this set (e.g. OGG), call the underlying OpenAI SDK directly."],"exampleFix":"// before\nvar settings = new OpenAITextToAudioExecutionSettings { GeneratedSpeechFormat = \"audio/mpeg\" };\n\n// after\nvar settings = new OpenAITextToAudioExecutionSettings { GeneratedSpeechFormat = \"mp3\" };","handlingStrategy":"validation","validationCode":"static readonly HashSet<string> SupportedFormats = new(StringComparer.OrdinalIgnoreCase)\n{\n    \"wav\", \"mp3\", \"opus\", \"flac\", \"aac\", \"pcm\"\n};\n\nvoid ValidateFormat(string? format)\n{\n    if (format is not null && !SupportedFormats.Contains(format.Trim()))\n        throw new ArgumentOutOfRangeException(nameof(format),\n            $\"Format must be one of: {string.Join(\", \", SupportedFormats)} (or null for default)\");\n}","typeGuard":null,"tryCatchPattern":"try { var audio = await ttsService.GetAudioContentAsync(text, settings); }\ncatch (NotSupportedException ex) when (ex.Message.Contains(\"format\"))\n{\n    settings.GeneratedSpeechFormat = null; // let API choose default\n    var audio = await ttsService.GetAudioContentAsync(text, settings);\n}","preventionTips":["Allow null format in configuration so the API default is used when you don't need a specific container.","Validate the format token at configuration-load time, not at call time."],"tags":["text-to-audio","format","validation","tts"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}