What causes "Vertex API version {apiVersion} is not supported." in microsoft/semantic-kernel?

Use VertexAIVersion.V1 or VertexAIVersion.V1_Beta explicitly.

microsoft/semantic-kernel · error · NotSupportedException

Vertex API version {apiVersion} is not supported.

Error message

Vertex API version {apiVersion} is not supported.

What it means

Thrown by ClientBase.GetApiVersionSubLink(VertexAIVersion) when the enum value is neither VertexAIVersion.V1 nor VertexAIVersion.V1_Beta. The switch maps V1 to 'v1' and V1_Beta to 'v1beta1'. This is the Vertex AI equivalent of the GoogleAIVersion guard, covering the same invalid-enum scenarios.

Source

Thrown at dotnet/src/Connectors/Connectors.Google/Core/ClientBase.cs:123

        }

        return httpRequestMessage;
    }

    protected static string GetApiVersionSubLink(GoogleAIVersion apiVersion)
        => apiVersion switch
        {
            GoogleAIVersion.V1 => "v1",
            GoogleAIVersion.V1_Beta => "v1beta",
            _ => throw new NotSupportedException($"Google API version {apiVersion} is not supported.")
        };

    protected static string GetApiVersionSubLink(VertexAIVersion apiVersion)
        => apiVersion switch
        {
            VertexAIVersion.V1 => "v1",
            VertexAIVersion.V1_Beta => "v1beta1",
            _ => throw new NotSupportedException($"Vertex API version {apiVersion} is not supported.")
        };

    /// <summary>
    /// Gets the Vertex AI endpoint base URI for the given location.
    /// The global location uses <c>https://aiplatform.googleapis.com</c> while
    /// regional locations use <c>https://{location}-aiplatform.googleapis.com</c>.
    /// </summary>
    protected static string GetVertexAIBaseUri(string location)
        => string.Equals(location, "global", StringComparison.OrdinalIgnoreCase)
            ? "https://aiplatform.googleapis.com"
            : $"https://{location}-aiplatform.googleapis.com";
}

View on GitHub (pinned to c028a0c7dc)

Solutions

Use VertexAIVersion.V1 or VertexAIVersion.V1_Beta explicitly.
Upgrade the Connectors.Google package if a new Vertex AI API version is required.
Avoid integer-to-enum casts for VertexAIVersion.

Example fix

// before — invalid cast
var version = (VertexAIVersion)configValue;

// after
var version = VertexAIVersion.V1;

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(VertexAIVersion), apiVersion) ||
    (apiVersion != VertexAIVersion.V1 && apiVersion != VertexAIVersion.V1_Beta))
{
    throw new ArgumentOutOfRangeException(nameof(apiVersion),
        $"VertexAIVersion must be V1 or V1_Beta. Got {apiVersion}.");
}

Type guard

static bool IsSupportedVertexVersion(VertexAIVersion v) =>
    v == VertexAIVersion.V1 || v == VertexAIVersion.V1_Beta;

Try / catch

null

Prevention

Always use the named VertexAIVersion enum values; never cast integers.
When upgrading the SDK, check for new enum members and verify connector support.

When it happens

Trigger: Casting an arbitrary integer to VertexAIVersion that does not map to V1 or V1_Beta. A future SDK version introduces a new VertexAIVersion member not handled by this connector.

Common situations: Same as error 326 but for Vertex AI: library version mismatch, invalid enum casts, dynamic/reflective enum construction.

Related errors

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