microsoft/aspire · error · ArgumentException

Unexpected MillisecondsDisplay value

Error message

Unexpected MillisecondsDisplay value: {millisecondsDisplay}.

What it means

GetPattern maps a MillisecondsDisplay enum value to a corresponding date/time format pattern from the supplied pattern set. It throws ArgumentException (with the parameter name) when the enum value is outside the defined None/Truncated/Full set — normally only possible via an invalid cast or a value from a newer enum version.

Solutions

Validate the value is a defined MillisecondsDisplay member (Enum.IsDefined) before passing it
Fix the source of the invalid value (config/settings store) so it contains 0, 1, or 2
If value comes from config parsing, use Enum.TryParse with a fallback default instead of a raw cast
Realign package versions if the value was produced by a newer Aspire version

Example fix

// before
var pattern = DateFormatStringsHelpers.GetPattern((MillisecondsDisplay)settings.MsDisplay, patterns);
// after
var msDisplay = Enum.IsDefined(typeof(MillisecondsDisplay), settings.MsDisplay)
    ? (MillisecondsDisplay)settings.MsDisplay
    : MillisecondsDisplay.None;
var pattern = DateFormatStringsHelpers.GetPattern(msDisplay, patterns);

Defensive patterns

Strategy: validation

Validate before calling

bool isValid = Enum.IsDefined(typeof(MillisecondsDisplay), millisecondsDisplay);
if (!isValid) millisecondsDisplay = MillisecondsDisplay.None;

Type guard

static bool IsDefinedMillisecondsDisplay(MillisecondsDisplay value) =>
    value is MillisecondsDisplay.None or MillisecondsDisplay.Truncated or MillisecondsDisplay.Full;

Try / catch

try { return DateFormatStringsHelpers.GetPattern(value, patterns); }
catch (ArgumentException) { return patterns.None; /* fall back to default pattern */ }

Prevention

Never cast ints to MillisecondsDisplay without Enum.IsDefined
Use Enum.TryParse when reading enum values from config or storage
Keep Aspire package versions aligned across components sharing settings

When it happens

Trigger: Passing a MillisecondsDisplay value that is not None, Truncated, or Full — e.g. an unchecked (MillisecondsDisplay)99 cast, deserialized/binary-copied enum data, or a value added in a newer package version while patterns were compiled against the old one.

Common situations: Reading a user preference (milliseconds display) from config stored as int and casting without validation; shared settings files written by a newer app version read by an older one.

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/4591b340d0aa3fba. Report an issue: GitHub.

Appendix: source

Thrown at src/Shared/DateFormatStringsHelpers.cs:124

            return pattern;
        }
    }

    internal static string GetLongTimePattern(CultureInfo cultureInfo, TimeFormat timeFormat, MillisecondsDisplay millisecondsDisplay)
        => GetPattern(GetDateFormatStrings(cultureInfo, timeFormat).LongTimePattern, millisecondsDisplay);

    internal static string GetShortDateLongTimePattern(CultureInfo cultureInfo, TimeFormat timeFormat, MillisecondsDisplay millisecondsDisplay)
        => GetPattern(GetDateFormatStrings(cultureInfo, timeFormat).ShortDateLongTimePattern, millisecondsDisplay);

    private static string GetPattern(CachedTimeFormatStrings patterns, MillisecondsDisplay millisecondsDisplay)
    {
        return millisecondsDisplay switch
        {
            MillisecondsDisplay.None => patterns.None,
            MillisecondsDisplay.Truncated => patterns.TruncatedMilliseconds,
            MillisecondsDisplay.Full => patterns.FullMilliseconds,
            _ => throw new ArgumentException($"Unexpected {nameof(MillisecondsDisplay)} value: {millisecondsDisplay}.", nameof(millisecondsDisplay))
        };
    }
}

View on GitHub (pinned to 25830f84bd)