The Azure scope value type

Error message

The Azure scope value type {value.GetType()} is not supported.

What it means

ResolveScopeValueAsync received a scope value whose runtime type is neither string nor IValueProvider, so it cannot be resolved. This is a programming/API-misuse error: an unsupported object was passed where a scope (subscription ID or resource group) is expected.

Solutions

Pass a string literal or variable of type string for the subscription ID / resource group
Pass an IValueProvider (e.g. a ParameterResource) instead of an unrelated object
Fix the variable's declared type at the call site so the compiler enforces string/IValueProvider
Check the API's XML docs for the accepted scope value types

Example fix

// before
// Guid subId = Guid.NewGuid();
// aks.WithScope(subId, resourceGroup); // unsupported type
// after
// string subId = "00000000-0000-0000-0000-000000000000";
// aks.WithScope(subId, resourceGroup);

Defensive patterns

Strategy: type-guard

Validate before calling

bool IsValidScope(object? v) => v is string { Length: > 0 } or IValueProvider;

Type guard

static bool IsValidScopeValue(object value) =>
    value is string { Length: > 0 } or IValueProvider;

Prevention

Declare scope variables as string or IValueProvider so the compiler catches misuse
Read the API docs for accepted scope value types
Pass the parameter resource itself, not its resolved Value or unrelated references

When it happens

Trigger: Calling the scope-configuration API with an arbitrary object (e.g. a resource reference, GUID, or custom type) instead of a string or IValueProvider.

Common situations: Passing a ParameterResource's Value object or an EndpointReference directly instead of the resource itself; refactoring left a variable of the wrong type; confusion between resource and value in the API.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/b08992380e46e2a2. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesEnvironmentResource.AksPipeline.cs:809

    /// <remarks>
    /// Matches <c>BicepProvisioner.ResolveScopeValueAsync</c>, including its refusal to accept a
    /// null result from a provider. Falling back to the app's own subscription in that case would
    /// be worse than failing: provisioning would have thrown, while the credential fetch would
    /// quietly target the wrong scope and could adopt a same-named cluster there. Empty is rejected
    /// for the same reason, since the string.IsNullOrEmpty checks downstream would treat it as
    /// unpinned. Nothing upstream rejects empty (the scope constructors and
    /// <c>AsExistingInResourceGroup</c> only guard against null), so a literal is checked too.
    /// </remarks>
    internal static async Task<string?> ResolveScopeValueAsync(object? value, CancellationToken cancellationToken)
        => value switch
        {
            null => null,
            string { Length: > 0 } s => s,
            IValueProvider provider when
                await provider.GetValueAsync(cancellationToken).ConfigureAwait(false) is { Length: > 0 } resolved => resolved,
            string or IValueProvider => throw new InvalidOperationException(
                "The Azure resource scope value cannot be null or empty."),
            _ => throw new NotSupportedException(
                $"The Azure scope value type {value.GetType()} is not supported.")
        };

    /// <summary>
    /// Resolves the subscription and resource group that this AKS cluster actually lives in.
    /// </summary>
    /// <remarks>
    /// A cluster adopted with <c>AsExistingInResourceGroup(...)</c> can sit in a different
    /// subscription and resource group than the one Aspire deploys the rest of the app into, and the
    /// provisioner targets that per-resource scope. The Azure CLI calls here have to agree with it,
    /// otherwise we would authenticate against the wrong subscription and could even find a
    /// same-named cluster in the wrong place. Values the resource does not pin fall back to the
    /// global deployment state.
    /// </remarks>
    internal static async Task<(string SubscriptionId, string? ResourceGroup)> ResolveDeploymentScopeAsync(
        object? scopedSubscription,
        object? scopedResourceGroup,
        IServiceProvider services,

View on GitHub (pinned to 25830f84bd)