microsoft/aspire · error · ArgumentException

AzureSandboxOptions.AutoSuspendEnabled must be set when…

Error message

AzureSandboxOptions.AutoSuspendEnabled must be set when configuring auto-suspend interval or mode.

What it means

Auto-suspend was partially configured: an auto-suspend interval and/or mode was supplied, but the AutoSuspendEnabled master switch was left unset (null). The library requires the enabling flag to be explicit whenever any auto-suspend detail is provided, to avoid silently guessing whether auto-suspend is on, and throws ArgumentException.

Solutions

Set AutoSuspendEnabled = true when you want auto-suspend, together with the interval/mode.
If auto-suspend is not wanted, remove the AutoSuspendInterval/AutoSuspendMode values instead of leaving them set.
Validate options before publishing: AutoSuspendEnabled must be non-null whenever either auto-suspend detail is provided.

Example fix

// before
new AzureSandboxOptions { AutoSuspendInterval = TimeSpan.FromMinutes(30) };

// after
new AzureSandboxOptions
{
    AutoSuspendEnabled = true,
    AutoSuspendInterval = TimeSpan.FromMinutes(30)
};

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try { builder.PublishAsAzureSandbox(options); } catch (ArgumentException ex) when (ex.Message.Contains("AutoSuspendEnabled must be set")) { /* set AutoSuspendEnabled or drop the interval/mode */ }

Prevention

Always pair Enabled flags with any detail values when constructing sandbox options.
Build options through a helper that sets Enabled = true whenever interval/mode are supplied.
Load options from configuration and validate all pairs before publishing.

When it happens

Trigger: Calling PublishAsAzureSandbox with AzureSandboxOptions where AutoSuspendEnabled is null while AutoSuspendInterval or AutoSuspendMode is non-null.

Common situations: Setting only AutoSuspendInterval (assuming the feature turns on implicitly); copying an options object where AutoSuspendEnabled was omitted by the caller; refactoring options and dropping the Enabled assignment.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

    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));
        }

        if (options.AutoDeleteEnabled is null &&
            (options.AutoDeleteInterval is not null || options.AutoDeleteTrigger is not null))
        {
            throw new ArgumentException(
                $"{nameof(AzureSandboxOptions.AutoDeleteEnabled)} must be set when configuring auto-delete interval or trigger.",
                nameof(options));
        }

        if (options.Endpoints is null)
        {
            return;
        }

        var names = new HashSet<string>(StringComparer.OrdinalIgnoreCase);

View on GitHub (pinned to 25830f84bd)