microsoft/aspire · error · ArgumentOutOfRangeException

The value cannot exceed

Error message

The value cannot exceed {maximum}.

What it means

Optional duration options have an upper bound enforced via the maximum parameter in ValidateOptionalWholeSecondDuration. When the supplied TimeSpan is valid in sign and precision but larger than the allowed maximum, an ArgumentOutOfRangeException names the parameter and states the limit.

Solutions

1. Reduce the duration to at or below the stated maximum in the message
2. Check the option's XML docs/readme for the documented maximum
3. Clamp before assignment: value > max ? max : value

Example fix

// before
var options = new AzureSandboxOptions { IdleTimeout = TimeSpan.FromHours(48) }; // exceeds max
// after
var options = new AzureSandboxOptions { IdleTimeout = TimeSpan.FromHours(4) }; // within maximum

if (value > maximum) value = maximum;

When it happens

Trigger: PublishAsAzureSandbox given a duration option exceeding the library-defined maximum, e.g. an idle timeout larger than the supported cap (value > maximum check).

Common situations: Setting very long timeouts assuming they are unbounded; copying a timeout from another product's docs; misreading seconds as minutes so the value overshoots the max.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• The value cannot be negative.
• The value must use whole-second precision.
• Endpoint option ' ' is configured more than once.
• Endpoint option names cannot be empty.
• Endpoint options cannot contain null values.

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

Appendix: source

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

    {
        if (value is null)
        {
            return;
        }

        if (value < TimeSpan.Zero)
        {
            throw new ArgumentOutOfRangeException(paramName, "The value cannot be negative.");
        }

        if (value.Value.Ticks % TimeSpan.TicksPerSecond != 0)
        {
            throw new ArgumentException("The value must use whole-second precision.", paramName);
        }

        if (maximum is not null && value > maximum)
        {
            throw new ArgumentOutOfRangeException(paramName, $"The value cannot exceed {maximum}.");
        }
    }

    private static void ValidateOptionalEnum<TEnum>(TEnum? value, string paramName)
        where TEnum : struct, Enum
    {
        if (value is not null && !Enum.IsDefined(value.Value))
        {
            throw new ArgumentException($"'{value}' is not a valid {typeof(TEnum).Name} value.", paramName);
        }
    }

    private static void EnsureSandboxPublisherValidationAdded(IDistributedApplicationBuilder builder)
    {
        if (builder.Services.Any(static descriptor => descriptor.ServiceType == typeof(AzureSandboxPipelineStepMarker)))
        {
            return;
        }

View on GitHub (pinned to 25830f84bd)