microsoft/aspire · error · ArgumentException

The value must use whole-second precision.

Error message

The value must use whole-second precision.

What it means

Optional duration options for Azure sandbox publishing must use whole-second precision. Sub-second values (milliseconds or ticks) cannot be represented in the Azure sandbox configuration, so any TimeSpan with a fractional-second component is rejected.

Solutions

1. Round the value to whole seconds before passing it, e.g. TimeSpan.FromSeconds(Math.Round(value.TotalSeconds))
2. Use TimeSpan.FromSeconds(2) instead of TimeSpan.FromSeconds(2.5)
3. Express the duration in seconds as an integer in your configuration

Example fix

// before
var options = new AzureSandboxOptions { IdleTimeout = TimeSpan.FromSeconds(1.5) };
// after
var options = new AzureSandboxOptions { IdleTimeout = TimeSpan.FromSeconds(2) };

if (value.Ticks % TimeSpan.TicksPerSecond != 0) value = TimeSpan.FromSeconds(Math.Round(value.TotalSeconds));

When it happens

Trigger: ValidateSandboxOptions receives e.g. TimeSpan.FromMilliseconds(1500) or TimeSpan.FromSeconds(1.5) for a duration option when calling PublishAsAzureSandbox.

Common situations: Passing a measured/elapsed duration that includes milliseconds; converting from a config value expressed in milliseconds; using TimeSpan.FromSeconds with a double literal like 2.5.

Understand the failure class

Background: "invalid duration" / "failed to parse duration": why your timeout, interval, or TTL string is rejected and which formats each library accepts — this error's family across 32 libraries.

Related errors

• The value cannot be negative.
• The value cannot exceed
• 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/65d486f2b5340d1f. Report an issue: GitHub.

Appendix: source

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

            }
        }
    }

    private static void ValidateOptionalWholeSecondDuration(TimeSpan? value, string paramName, TimeSpan? maximum = null)
    {
        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)

View on GitHub (pinned to 25830f84bd)