{"record":{"id":"cb91f4ccfc38863c","repo":"microsoft/semantic-kernel","slug":"the-service-version-serviceversion-is-not-supp","errorCode":null,"errorMessage":"The service version '{serviceVersion}' is not supported.","messagePattern":"The service version '(.+?)' is not supported\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Connectors/Connectors.AzureOpenAI/Core/AzureClientCore.cs","lineNumber":144,"sourceCode":"    /// <returns>An instance of <see cref=\"OpenAIClientOptions\"/>.</returns>\n    internal static AzureOpenAIClientOptions GetAzureOpenAIClientOptions(HttpClient? httpClient, string? serviceVersion = null)\n    {\n        AzureOpenAIClientOptions.ServiceVersion? sdkVersion = null;\n        if (serviceVersion is not null)\n        {\n            sdkVersion = serviceVersion.ToUpperInvariant() switch // Azure SDK versioning\n            {\n                \"2024-06-01\" or \"V2024_06_01\" or \"2024_06_01\" => AzureOpenAIClientOptions.ServiceVersion.V2024_06_01,\n                \"2024-10-21\" or \"V2024_10_21\" or \"2024_10_21\" => AzureOpenAIClientOptions.ServiceVersion.V2024_10_21,\n                \"2024-08-01-PREVIEW\" or \"V2024_08_01_PREVIEW\" or \"2024_08_01_PREVIEW\" => AzureOpenAIClientOptions.ServiceVersion.V2024_08_01_Preview,\n                \"2024-09-01-PREVIEW\" or \"V2024_09_01_PREVIEW\" or \"2024_09_01_PREVIEW\" => AzureOpenAIClientOptions.ServiceVersion.V2024_09_01_Preview,\n                \"2024-10-01-PREVIEW\" or \"V2024_10_01_PREVIEW\" or \"2024_10_01_PREVIEW\" => AzureOpenAIClientOptions.ServiceVersion.V2024_10_01_Preview,\n                \"2024-12-01-PREVIEW\" or \"V2024_12_01_PREVIEW\" or \"2024_12_01_PREVIEW\" => AzureOpenAIClientOptions.ServiceVersion.V2024_12_01_Preview,\n                \"2025-01-01-PREVIEW\" or \"V2025_01_01_PREVIEW\" or \"2025_01_01_PREVIEW\" => AzureOpenAIClientOptions.ServiceVersion.V2025_01_01_Preview,\n                \"2025-03-01-PREVIEW\" or \"V2025_03_01_PREVIEW\" or \"2025_03_01_PREVIEW\" => AzureOpenAIClientOptions.ServiceVersion.V2025_03_01_Preview,\n                \"2025-04-01-PREVIEW\" or \"V2025_04_01_PREVIEW\" or \"2025_04_01_PREVIEW\" => AzureOpenAIClientOptions.ServiceVersion.V2025_04_01_Preview,\n\n                _ => throw new NotSupportedException($\"The service version '{serviceVersion}' is not supported.\")\n            };\n        }\n\n        AzureOpenAIClientOptions options = sdkVersion is not null\n            ? new AzureOpenAIClientOptions(sdkVersion.Value)\n            : new();\n\n        options.UserAgentApplicationId = HttpHeaderConstant.Values.UserAgent;\n        options.AddPolicy(CreateRequestHeaderPolicy(HttpHeaderConstant.Names.SemanticKernelVersion, HttpHeaderConstant.Values.GetAssemblyVersion(typeof(AzureClientCore))), PipelinePosition.PerCall);\n\n        if (httpClient is not null)\n        {\n            options.Transport = new HttpClientPipelineTransport(httpClient);\n            options.RetryPolicy = new ClientRetryPolicy(maxRetries: 0); // Disable Azure SDK retry policy if and only if a custom HttpClient is provided.\n            options.NetworkTimeout = Timeout.InfiniteTimeSpan; // Disable Azure SDK default timeout\n        }\n\n        return options;","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Connectors/Connectors.AzureOpenAI/Core/AzureClientCore.cs#L126-L162","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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'."],"exampleFix":"// before — unsupported version string\nvar service = new AzureOpenAITextToImageService(\n    \"my-deployment\", endpoint, apiKey, apiVersion: \"2024-08-01\");\n\n// after — either omit (uses default) or use an exact recognized value\nvar service = new AzureOpenAITextToImageService(\n    \"my-deployment\", endpoint, apiKey); // apiVersion defaults to SDK default","handlingStrategy":"validation","validationCode":"// Validate apiVersion before constructing the service\nstatic readonly HashSet<string> SupportedVersions = new(StringComparer.OrdinalIgnoreCase)\n{\n    \"2024-06-01\", \"V2024_06_01\", \"2024_06_01\",\n    \"2024-10-21\", \"V2024_10_21\", \"2024_10_21\",\n    \"2024-08-01-PREVIEW\", \"V2024_08_01_PREVIEW\", \"2024_08_01_PREVIEW\",\n    \"2024-09-01-PREVIEW\", \"V2024_09_01_PREVIEW\", \"2024_09_01_PREVIEW\",\n    \"2024-10-01-PREVIEW\", \"V2024_10_01_PREVIEW\", \"2024_10_01_PREVIEW\",\n    \"2024-12-01-PREVIEW\", \"V2024_12_01_PREVIEW\", \"2024_12_01_PREVIEW\",\n    \"2025-01-01-PREVIEW\", \"V2025_01_01_PREVIEW\", \"2025_01_01_PREVIEW\",\n    \"2025-03-01-PREVIEW\", \"V2025_03_01_PREVIEW\", \"2025_03_01_PREVIEW\",\n    \"2025-04-01-PREVIEW\", \"V2025_04_01_PREVIEW\", \"2025_04_01_PREVIEW\",\n};\n\nif (apiVersion is not null && !SupportedVersions.Contains(apiVersion))\n    throw new ArgumentException($\"Unsupported API version '{apiVersion}'. Supported: {string.Join(\", \", SupportedVersions)}\");","typeGuard":"static bool IsSupportedAzureVersion(string? v) =>\n    v is null || // null means use SDK default\n    new[] { \"2024-06-01\", \"2024-10-21\", \"2024-08-01-PREVIEW\", \"2024-09-01-PREVIEW\",\n            \"2024-10-01-PREVIEW\", \"2024-12-01-PREVIEW\", \"2025-01-01-PREVIEW\",\n            \"2025-03-01-PREVIEW\", \"2025-04-01-PREVIEW\" }\n        .Contains(v, StringComparer.OrdinalIgnoreCase);","tryCatchPattern":"try { var service = new AzureOpenAITextToImageService(deploy, endpoint, key, apiVersion: ver); }\ncatch (NotSupportedException ex) when (ex.Message.Contains(\"service version\"))\n{\n    logger.LogWarning(\"Version {Ver} not supported, falling back to default\", ver);\n    service = new AzureOpenAITextToImageService(deploy, endpoint, key); // no apiVersion\n}","preventionTips":["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."],"tags":["azure-openai","versioning","configuration","notsupported"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}