microsoft/semantic-kernel · error · NotSupportedException

The voice '{voice}' is not supported.

Error message

The voice '{voice}' is not supported.

What it means

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.

Source

Thrown at dotnet/src/Connectors/Connectors.OpenAI/Core/ClientCore.TextToAudio.cs:57

            ResponseFormat = responseFormat,
            SpeedRatio = audioExecutionSettings.Speed,
        };

        ClientResult<BinaryData> response = await RunRequestAsync(() => this.Client!.GetAudioClient(targetModel).GenerateSpeechAsync(prompt, GetGeneratedSpeechVoice(audioExecutionSettings?.Voice), options, cancellationToken)).ConfigureAwait(false);

        return [new AudioContent(response.Value.ToArray(), mimeType)];
    }

    private static GeneratedSpeechVoice GetGeneratedSpeechVoice(string? voice)
        => voice?.ToUpperInvariant() switch
        {
            "ALLOY" => GeneratedSpeechVoice.Alloy,
            "ECHO" => GeneratedSpeechVoice.Echo,
            "FABLE" => GeneratedSpeechVoice.Fable,
            "ONYX" => GeneratedSpeechVoice.Onyx,
            "NOVA" => GeneratedSpeechVoice.Nova,
            "SHIMMER" => GeneratedSpeechVoice.Shimmer,
            _ => throw new NotSupportedException($"The voice '{voice}' is not supported."),
        };

    private static (GeneratedSpeechFormat? Format, string? MimeType) GetGeneratedSpeechFormatAndMimeType(string? format)
    {
        switch (format?.ToUpperInvariant())
        {
            case "WAV": return (GeneratedSpeechFormat.Wav, "audio/wav");
            case "MP3": return (GeneratedSpeechFormat.Mp3, "audio/mpeg");
            case "OPUS": return (GeneratedSpeechFormat.Opus, "audio/opus");
            case "FLAC": return (GeneratedSpeechFormat.Flac, "audio/flac");
            case "AAC": return (GeneratedSpeechFormat.Aac, "audio/aac");
            case "PCM": return (GeneratedSpeechFormat.Pcm, "audio/l16");
            case null: return (null, null);
            default: throw new NotSupportedException($"The format '{format}' is not supported.");
        }
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set Voice to one of: alloy, echo, fable, onyx, nova, shimmer (case-insensitive).
2. Upgrade the Connectors.OpenAI package to a version that includes the new voice you need.
3. Trim/normalize the voice string before assignment to rule out whitespace or casing artifacts.
4. If you must use an unsupported voice, call the OpenAI SDK's speech endpoint directly instead of through this connector.

Example fix

// before
var settings = new OpenAITextToAudioExecutionSettings { Voice = "coral" };

// after — use a supported voice, or upgrade the package
var settings = new OpenAITextToAudioExecutionSettings { Voice = "alloy" };

static readonly HashSet<string> SupportedVoices = new(StringComparer.OrdinalIgnoreCase)
{
    "alloy", "echo", "fable", "onyx", "nova", "shimmer"
};

void ValidateVoice(string? voice)
{
    if (voice is not null && !SupportedVoices.Contains(voice.Trim()))
        throw new ArgumentOutOfRangeException(nameof(voice),
            $"Voice must be one of: {string.Join(", ", SupportedVoices)}");
}

try { var audio = await ttsService.GetAudioContentAsync(text, settings); }
catch (NotSupportedException ex) when (ex.Message.Contains("voice"))
{
    settings.Voice = "alloy"; // fallback to a known voice
    var audio = await ttsService.GetAudioContentAsync(text, settings);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The format '{format}' is not supported.
• {type(self)} service failed to generate audio
• MaxTokens {maxTokens} is not valid, the value must be greate
• Invalid message role `{message.role.value}`. Allowed roles a
• Invalid message role `{message.role.value}`. Allowed roles a

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