dotnet/wpf · error · InvalidEnumArgumentException

InvalidEnumArgumentException("Substitution", (int)value…

Error message

InvalidEnumArgumentException("Substitution", (int)value, typeof(NumberSubstitutionMethod))

What it means

NumberSubstitution.Substitution setter validates the value against the NumberSubstitutionMethod enum ((uint)value > NumberSubstitutionMethod.Traditional) and throws InvalidEnumArgumentException("Substitution", ...). Valid values are AsCulture, Context, European, NativeNational, Traditional.

Solutions

Assign only named enum members such as NumberSubstitutionMethod.Context
Validate integers with Enum.IsDefined(typeof(NumberSubstitutionMethod), v) before casting
Clamp or reject persisted config values outside 0..4 and fall back to Context
Fix the offending serialized/config value to a defined enum number

Example fix

// before
numberSubstitution.Substitution = (NumberSubstitutionMethod)storedInt; // storedInt = 9
// after
numberSubstitution.Substitution = Enum.IsDefined(typeof(NumberSubstitutionMethod), storedInt)
    ? (NumberSubstitutionMethod)storedInt
    : NumberSubstitutionMethod.Context;

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(NumberSubstitutionMethod), value)) value = NumberSubstitutionMethod.Context;

Type guard

bool IsValidSubstitutionMethod(int v) => v >= 0 && v <= (int)NumberSubstitutionMethod.Traditional;

Try / catch

try { numberSubstitution.Substitution = method; }
catch (InvalidEnumArgumentException ex) { log.Warn("Invalid Substitution, using Context", ex); numberSubstitution.Substitution = NumberSubstitutionMethod.Context; }

Prevention

Only assign named NumberSubstitutionMethod members
Validate persisted integers with Enum.IsDefined
Do not bind raw integer inputs directly to the property

When it happens

Trigger: Assigning Substitution an out-of-range integer cast to NumberSubstitutionMethod (e.g. (NumberSubstitutionMethod)9), or restoring a serialized value not defined in the enum.

Common situations: Persisting the substitution method as int in config and the stored value exceeds the enum; data migrated from a different framework version; binding a raw slider/combobox index directly to the property.

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 dotnet/wpf@81131a70a4 (2026-09-14). Data as JSON: /api/errors/6f7d693031bd31ae. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/Media/textformatting/NumberSubstitution.cs:123

        /// <param name="value">CultureInfo object to validate; the type is assumed
        /// to be CultureInfo as the type is validated by the property engine.</param>
        /// <returns>Returns true if it's a valid culture, false if not.</returns>
        private static bool IsValidCultureOverrideValue(object value)
        {
            return IsValidCultureOverride((CultureInfo)value);
        }

        /// <summary>
        /// Specifies the type of number substitution to perform, if any.
        /// </summary>
        public NumberSubstitutionMethod Substitution
        {
            get { return _substitution; }

            set
            {
                if ((uint)value > (uint)NumberSubstitutionMethod.Traditional)
                    throw new InvalidEnumArgumentException("Substitution", (int)value, typeof(NumberSubstitutionMethod));

                _substitution = value;
            }
        }

        /// <summary>
        /// DP For CultureSource
        /// </summary>
        public static readonly DependencyProperty CultureSourceProperty =
                    DependencyProperty.RegisterAttached(
                        "CultureSource",
                        typeof(NumberCultureSource),
                        typeof(NumberSubstitution));

        /// <summary>
        /// Setter for NumberSubstitution DependencyProperty
        /// </summary>
        public static void SetCultureSource(DependencyObject target, NumberCultureSource value)

View on GitHub (pinned to 81131a70a4)