What causes "'{options.Tier}' is not a valid Azure sandbox tier." in microsoft/aspire?

Set Tier to one of the enum's defined members (use the enum type directly instead of casting ints).

microsoft/aspire · error · ArgumentException

' ' is not a valid Azure sandbox tier.

Error message

'{options.Tier}' is not a valid Azure sandbox tier.

What it means

AzureSandboxOptions.Tier was validated with Enum.IsDefined and the supplied value is not a defined member of the sandbox tier enum. Because Tier is typed as the enum, this typically occurs when an out-of-range numeric value or a stale/unsupported tier was supplied, and the library refuses it via ArgumentException.

Solutions

Set Tier to one of the enum's defined members (use the enum type directly instead of casting ints).
Validate any externally sourced tier value against Enum.IsDefined(options.Tier) before calling PublishAsAzureSandbox.
Check the package version's tier enum members and update configuration referencing an old or renamed tier.

Example fix

// before
var options = new AzureSandboxOptions { Tier = (SandboxTier)configValue };

// after
var options = new AzureSandboxOptions
{
    Tier = Enum.IsDefined(typeof(SandboxTier), configValue)
        ? (SandboxTier)configValue
        : throw new ArgumentException($"Unknown sandbox tier: {configValue}")
};

Defensive patterns

Strategy: validation

Validate before calling

if (options.Tier is SandboxTier t && !Enum.IsDefined(t))
{
    throw new ArgumentException($"'{options.Tier}' is not a valid Azure sandbox tier.");
}

Type guard

bool IsValidTier<T>(T value) where T : struct, Enum => Enum.IsDefined(value);

Try / catch

try { builder.PublishAsAzureSandbox(options); } catch (ArgumentException ex) when (ex.Message.Contains("not a valid Azure sandbox tier")) { /* correct the Tier value or pin the package version */ }

Prevention

Never cast raw ints/strings to the tier enum without Enum.IsDefined/Enum.TryParse checks.
Keep tier values in configuration validated at startup.
Check enum members after upgrading or downgrading the package version.

When it happens

Trigger: Calling PublishAsAzureSandbox with options whose Tier is an enum value not defined by the current tier enum — e.g. casting an arbitrary int/long to the tier type, deserializing an unrecognized tier string/number from configuration, or using a tier from a different package version.

Common situations: Loading sandbox tier from app configuration (appsettings/env) without validating; casting config strings to the enum via (Tier)intValue; a package upgrade/downgrade renaming or removing a tier value that older config still references.

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/01496f035c5a2e2c. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Sandboxes/AzureSandboxesExtensions.cs:366

        // https://learn.microsoft.com/azure/templates/microsoft.authorization/2022-04-01/roleassignments
        infrastructure.Add(new RoleAssignment($"{sandboxGroup.BicepIdentifier}_deploymentPrincipalDataOwner")
        {
            Name = BicepFunction.CreateGuid(
                sandboxGroup.Id,
                principalId,
                BicepFunction.GetSubscriptionResourceId("Microsoft.Authorization/roleDefinitions", SandboxGroupDataOwnerRoleId)),
            Scope = new IdentifierExpression(sandboxGroup.BicepIdentifier),
            PrincipalType = principalType,
            PrincipalId = principalId,
            RoleDefinitionId = BicepFunction.GetSubscriptionResourceId("Microsoft.Authorization/roleDefinitions", SandboxGroupDataOwnerRoleId)
        });
    }

    private static void ValidateSandboxOptions(AzureSandboxOptions options)
    {
        if (!Enum.IsDefined(options.Tier))
        {
            throw new ArgumentException($"'{options.Tier}' is not a valid Azure sandbox tier.", nameof(options));
        }

        ValidateOptionalWholeSecondDuration(
            options.AutoSuspendInterval,
            nameof(AzureSandboxOptions.AutoSuspendInterval),
            TimeSpan.FromSeconds(int.MaxValue));
        ValidateOptionalEnum(options.AutoSuspendMode, nameof(AzureSandboxOptions.AutoSuspendMode));
        ValidateOptionalWholeSecondDuration(options.AutoDeleteInterval, nameof(AzureSandboxOptions.AutoDeleteInterval));
        ValidateOptionalEnum(options.AutoDeleteTrigger, nameof(AzureSandboxOptions.AutoDeleteTrigger));

        if (options.AutoSuspendEnabled is null &&
            (options.AutoSuspendInterval is not null || options.AutoSuspendMode is not null))
        {
            throw new ArgumentException(
                $"{nameof(AzureSandboxOptions.AutoSuspendEnabled)} must be set when configuring auto-suspend interval or mode.",
                nameof(options));
        }

View on GitHub (pinned to 25830f84bd)