{"record":{"id":"b8e260839931feb0","repo":"microsoft/semantic-kernel","slug":"the-voice-voice-is-not-supported","errorCode":null,"errorMessage":"The voice '{voice}' is not supported.","messagePattern":"The voice '(.+?)' is not supported\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Connectors/Connectors.OpenAI/Core/ClientCore.TextToAudio.cs","lineNumber":57,"sourceCode":"            ResponseFormat = responseFormat,\n            SpeedRatio = audioExecutionSettings.Speed,\n        };\n\n        ClientResult<BinaryData> response = await RunRequestAsync(() => this.Client!.GetAudioClient(targetModel).GenerateSpeechAsync(prompt, GetGeneratedSpeechVoice(audioExecutionSettings?.Voice), options, cancellationToken)).ConfigureAwait(false);\n\n        return [new AudioContent(response.Value.ToArray(), mimeType)];\n    }\n\n    private static GeneratedSpeechVoice GetGeneratedSpeechVoice(string? voice)\n        => voice?.ToUpperInvariant() switch\n        {\n            \"ALLOY\" => GeneratedSpeechVoice.Alloy,\n            \"ECHO\" => GeneratedSpeechVoice.Echo,\n            \"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":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Connectors/Connectors.OpenAI/Core/ClientCore.TextToAudio.cs#L39-L75","documentation":"The text-to-speech voice string supplied in execution settings is matched case-insensitively against a fixed allow-list (ALLOY, ECHO, FABLE, ONYX, NOVA, SHIMMER). Any value not in that set throws NotSupportedException before the request is sent. The connector does not forward arbitrary voice names to the API.","triggerScenarios":"Passing a voice name in OpenAITextToAudioExecutionSettings.Voice that is not one of the six built-in voices. For example using a new OpenAI voice the connector version doesn't yet know about, a typo, or a value intended for a different TTS provider.","commonSituations":"OpenAI releases a new voice (e.g. 'coral', 'sage') that predates your installed connector version. Misspelling a voice like 'NOVA ' (trailing space) or 'nova2'. Migrating from another TTS SDK that accepted different voice identifiers.","solutions":["Set Voice to one of: alloy, echo, fable, onyx, nova, shimmer (case-insensitive).","Upgrade the Connectors.OpenAI package to a version that includes the new voice you need.","Trim/normalize the voice string before assignment to rule out whitespace or casing artifacts.","If you must use an unsupported voice, call the OpenAI SDK's speech endpoint directly instead of through this connector."],"exampleFix":"// before\nvar settings = new OpenAITextToAudioExecutionSettings { Voice = \"coral\" };\n\n// after — use a supported voice, or upgrade the package\nvar settings = new OpenAITextToAudioExecutionSettings { Voice = \"alloy\" };","handlingStrategy":"validation","validationCode":"static readonly HashSet<string> SupportedVoices = new(StringComparer.OrdinalIgnoreCase)\n{\n    \"alloy\", \"echo\", \"fable\", \"onyx\", \"nova\", \"shimmer\"\n};\n\nvoid ValidateVoice(string? voice)\n{\n    if (voice is not null && !SupportedVoices.Contains(voice.Trim()))\n        throw new ArgumentOutOfRangeException(nameof(voice),\n            $\"Voice must be one of: {string.Join(\", \", SupportedVoices)}\");\n}","typeGuard":null,"tryCatchPattern":"try { var audio = await ttsService.GetAudioContentAsync(text, settings); }\ncatch (NotSupportedException ex) when (ex.Message.Contains(\"voice\"))\n{\n    settings.Voice = \"alloy\"; // fallback to a known voice\n    var audio = await ttsService.GetAudioContentAsync(text, settings);\n}","preventionTips":["Centralize voice selection in configuration and validate against the allow-list at startup.","After upgrading the connector, check release notes for newly added voices."],"tags":["text-to-audio","voice","validation","tts","openai"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}