What causes "The service version '{serviceVersion}' is not supported." in microsoft/semantic-kernel?

Check the switch statement in the source for the exact supported version strings and use one of them verbatim.

microsoft/semantic-kernel · error · NotSupportedException

The service version '{serviceVersion}' is not supported.

Error message

The service version '{serviceVersion}' is not supported.

What it means

Thrown by AzureClientCore.GetAzureOpenAIClientOptions when the apiVersion string does not match any known Azure OpenAI service version after ToUpperInvariant normalization. The switch covers specific GA and preview version strings (e.g. '2024-06-01', '2024-10-21', and multiple preview versions through '2025-04-01-PREVIEW'). An unrecognized version means the connector cannot map it to an AzureOpenAIClientOptions.ServiceVersion enum value.

Source

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

    /// <returns>An instance of <see cref="OpenAIClientOptions"/>.</returns>
    internal static AzureOpenAIClientOptions GetAzureOpenAIClientOptions(HttpClient? httpClient, string? serviceVersion = null)
    {
        AzureOpenAIClientOptions.ServiceVersion? sdkVersion = null;
        if (serviceVersion is not null)
        {
            sdkVersion = serviceVersion.ToUpperInvariant() switch // Azure SDK versioning
            {
                "2024-06-01" or "V2024_06_01" or "2024_06_01" => AzureOpenAIClientOptions.ServiceVersion.V2024_06_01,
                "2024-10-21" or "V2024_10_21" or "2024_10_21" => AzureOpenAIClientOptions.ServiceVersion.V2024_10_21,
                "2024-08-01-PREVIEW" or "V2024_08_01_PREVIEW" or "2024_08_01_PREVIEW" => AzureOpenAIClientOptions.ServiceVersion.V2024_08_01_Preview,
                "2024-09-01-PREVIEW" or "V2024_09_01_PREVIEW" or "2024_09_01_PREVIEW" => AzureOpenAIClientOptions.ServiceVersion.V2024_09_01_Preview,
                "2024-10-01-PREVIEW" or "V2024_10_01_PREVIEW" or "2024_10_01_PREVIEW" => AzureOpenAIClientOptions.ServiceVersion.V2024_10_01_Preview,
                "2024-12-01-PREVIEW" or "V2024_12_01_PREVIEW" or "2024_12_01_PREVIEW" => AzureOpenAIClientOptions.ServiceVersion.V2024_12_01_Preview,
                "2025-01-01-PREVIEW" or "V2025_01_01_PREVIEW" or "2025_01_01_PREVIEW" => AzureOpenAIClientOptions.ServiceVersion.V2025_01_01_Preview,
                "2025-03-01-PREVIEW" or "V2025_03_01_PREVIEW" or "2025_03_01_PREVIEW" => AzureOpenAIClientOptions.ServiceVersion.V2025_03_01_Preview,
                "2025-04-01-PREVIEW" or "V2025_04_01_PREVIEW" or "2025_04_01_PREVIEW" => AzureOpenAIClientOptions.ServiceVersion.V2025_04_01_Preview,

                _ => throw new NotSupportedException($"The service version '{serviceVersion}' is not supported.")
            };
        }

        AzureOpenAIClientOptions options = sdkVersion is not null
            ? new AzureOpenAIClientOptions(sdkVersion.Value)
            : new();

        options.UserAgentApplicationId = HttpHeaderConstant.Values.UserAgent;
        options.AddPolicy(CreateRequestHeaderPolicy(HttpHeaderConstant.Names.SemanticKernelVersion, HttpHeaderConstant.Values.GetAssemblyVersion(typeof(AzureClientCore))), PipelinePosition.PerCall);

        if (httpClient is not null)
        {
            options.Transport = new HttpClientPipelineTransport(httpClient);
            options.RetryPolicy = new ClientRetryPolicy(maxRetries: 0); // Disable Azure SDK retry policy if and only if a custom HttpClient is provided.
            options.NetworkTimeout = Timeout.InfiniteTimeSpan; // Disable Azure SDK default timeout
        }

        return options;

View on GitHub (pinned to c028a0c7dc)

Solutions

Check the switch statement in the source for the exact supported version strings and use one of them verbatim.
If you need a newer API version, upgrade the Connectors.AzureOpenAI NuGet package to a release that lists your version.
Pass null for apiVersion to let the SDK use its default (latest GA) version instead of pinning a specific one.
Verify the version string format: GA versions use 'YYYY-MM-DD', preview versions use 'YYYY-MM-DD-PREVIEW'.

Example fix

// before — unsupported version string
var service = new AzureOpenAITextToImageService(
    "my-deployment", endpoint, apiKey, apiVersion: "2024-08-01");

// after — either omit (uses default) or use an exact recognized value
var service = new AzureOpenAITextToImageService(
    "my-deployment", endpoint, apiKey); // apiVersion defaults to SDK default

Defensive patterns

Strategy: validation

Validate before calling

// Validate apiVersion before constructing the service
static readonly HashSet<string> SupportedVersions = new(StringComparer.OrdinalIgnoreCase)
{
    "2024-06-01", "V2024_06_01", "2024_06_01",
    "2024-10-21", "V2024_10_21", "2024_10_21",
    "2024-08-01-PREVIEW", "V2024_08_01_PREVIEW", "2024_08_01_PREVIEW",
    "2024-09-01-PREVIEW", "V2024_09_01_PREVIEW", "2024_09_01_PREVIEW",
    "2024-10-01-PREVIEW", "V2024_10_01_PREVIEW", "2024_10_01_PREVIEW",
    "2024-12-01-PREVIEW", "V2024_12_01_PREVIEW", "2024_12_01_PREVIEW",
    "2025-01-01-PREVIEW", "V2025_01_01_PREVIEW", "2025_01_01_PREVIEW",
    "2025-03-01-PREVIEW", "V2025_03_01_PREVIEW", "2025_03_01_PREVIEW",
    "2025-04-01-PREVIEW", "V2025_04_01_PREVIEW", "2025_04_01_PREVIEW",
};

if (apiVersion is not null && !SupportedVersions.Contains(apiVersion))
    throw new ArgumentException($"Unsupported API version '{apiVersion}'. Supported: {string.Join(", ", SupportedVersions)}");

Type guard

static bool IsSupportedAzureVersion(string? v) =>
    v is null || // null means use SDK default
    new[] { "2024-06-01", "2024-10-21", "2024-08-01-PREVIEW", "2024-09-01-PREVIEW",
            "2024-10-01-PREVIEW", "2024-12-01-PREVIEW", "2025-01-01-PREVIEW",
            "2025-03-01-PREVIEW", "2025-04-01-PREVIEW" }
        .Contains(v, StringComparer.OrdinalIgnoreCase);

Try / catch

try { var service = new AzureOpenAITextToImageService(deploy, endpoint, key, apiVersion: ver); }
catch (NotSupportedException ex) when (ex.Message.Contains("service version"))
{
    logger.LogWarning("Version {Ver} not supported, falling back to default", ver);
    service = new AzureOpenAITextToImageService(deploy, endpoint, key); // no apiVersion
}

Prevention

Omit apiVersion to use the SDK default when you don't need to pin a specific version.
Cross-check the version string against the source switch statement in AzureClientCore.GetAzureOpenAIClientOptions.
Upgrade the Connectors.AzureOpenAI package when adopting new Azure OpenAI API versions.

When it happens

Trigger: Passing an apiVersion string (either to AzureClientCore or to a service constructor that forwards it) that is not one of the exact recognized values. The comparison is case-insensitive (ToUpperInvariant is applied first) but the string must match one of the listed version tokens exactly.

Common situations: Using a newer Azure OpenAI API version not yet supported by the installed connector package. Typo in the version string (e.g. '2024-10-22' instead of '2024-10-21'). Using a date format without the preview suffix when the version only exists as a preview (e.g. '2024-08-01' instead of '2024-08-01-PREVIEW'). Upgrading the Azure SDK without upgrading the Semantic Kernel connector.

Related errors

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