microsoft/aspire · error · InvalidOperationException

Unsupported Azure sandbox tier

Error message

Unsupported Azure sandbox tier '{options?.Tier}'.

What it means

The sandbox tier selection uses a switch expression over AzureSandboxTier with resource sizes for ExtraSmall through ExtraLarge; any other value falls to the default arm, which throws InvalidOperationException naming the supplied tier. This guards against invalid casts or out-of-range enum values.

Solutions

  1. Set Tier to one of the supported values: ExtraSmall, Small, Medium, Large, or ExtraLarge.
  2. Validate/normalize the tier when reading it from config (parse with Enum.TryParse and reject unknown values).
  3. If you genuinely need a new tier, it must be added to the switch in CreateSandboxSpec; otherwise use the nearest supported size.

Example fix

// before
options.Tier = (AzureSandboxTier)7; // undefined
// after
options.Tier = AzureSandboxTier.Large;
Defensive patterns

Strategy: validation

Validate before calling

static bool IsSupportedTier(AzureSandboxTier t) =>
    t is AzureSandboxTier.ExtraSmall or AzureSandboxTier.Small
        or AzureSandboxTier.Medium or AzureSandboxTier.Large
        or AzureSandboxTier.ExtraLarge;

Type guard

bool TryParseTier(string? s, out AzureSandboxTier tier) =>
    Enum.TryParse(s, ignoreCase: true, out tier) && IsSupportedTier(tier);

Try / catch

try { await deployment.DeployAsync(...); }
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Unsupported Azure sandbox tier"))
{ /* correct options.Tier to a supported value and retry */ }

Prevention

When it happens

Trigger: Configuring AzureSandboxOptions.Tier with an invalid value — typically an out-of-range int cast to AzureSandboxTier, a deserialized garbage value from config/JSON, or a newer enum member not yet handled by this switch.

Common situations: Loading sandbox options from environment variables or appsettings where the tier is parsed from a string/number without validation, or version skew between a newer CLI writing a tier value the deployment code does not know.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Sandboxes/AzureSandboxContainerDeployment.cs:815

            appIdentityAnnotation.IdentityResource is not AzureUserAssignedIdentityResource userAssignedIdentity)
        {
            return;
        }

        environmentVariables.TryAdd("AZURE_CLIENT_ID", GetRequiredOutput(userAssignedIdentity, "clientId"));
    }

    internal static AzureDevComputeSandboxResources CreateSandboxResources(AzureSandboxContainerResource resource)
    {
        var options = GetAzureSandboxContainerOptions(resource.TargetResource);
        return (options?.Tier ?? AzureSandboxTier.Medium) switch
        {
            AzureSandboxTier.ExtraSmall => new() { Cpu = "250m", Memory = "512Mi", Disk = "20480Mi" },
            AzureSandboxTier.Small => new() { Cpu = "500m", Memory = "1024Mi", Disk = "20480Mi" },
            AzureSandboxTier.Medium => new() { Cpu = "1000m", Memory = "2048Mi", Disk = "20480Mi" },
            AzureSandboxTier.Large => new() { Cpu = "2000m", Memory = "4096Mi", Disk = "40960Mi" },
            AzureSandboxTier.ExtraLarge => new() { Cpu = "4000m", Memory = "8192Mi", Disk = "81920Mi" },
            _ => throw new InvalidOperationException($"Unsupported Azure sandbox tier '{options?.Tier}'.")
        };
    }

    internal static AzureDevComputeSandboxEgressPolicy CreateEgressPolicy(IEnumerable<string> allowedHosts)
    {
        var normalizedHosts = allowedHosts
            .Where(static host => Uri.CheckHostName(host) is not UriHostNameType.Unknown)
            .Where(IsOutboundHost)
            .Distinct(StringComparer.OrdinalIgnoreCase)
            .Order(StringComparer.OrdinalIgnoreCase)
            .ToArray();

        return new AzureDevComputeSandboxEgressPolicy
        {
            DefaultAction = "Deny",
            TrafficInspection = "Full",
            HostRules =
            [

View on GitHub (pinned to 25830f84bd)