dotnet/wpf · error · ArgumentException

SR.DefaultValueMayNotBeUnset

Error message

SR.DefaultValueMayNotBeUnset

What it means

PropertyMetadata.DefaultValue rejects DependencyProperty.UnsetValue: assigning it throws ArgumentException with DefaultValueMayNotBeUnset. UnsetValue is the property system's internal sentinel for 'no value', so it is not a legal default value for metadata.

Solutions

  1. Assign null (for reference types) or a valid typed default instead of DependencyProperty.UnsetValue.
  2. If the goal is to inherit the base default, do not set DefaultValue at all — omit it in OverrideMetadata so Merge keeps the base value.
  3. Guard helper code: skip or translate UnsetValue before passing into PropertyMetadata.

Example fix

// before
var meta = new PropertyMetadata(DependencyProperty.UnsetValue); // throws

// after
var meta = new PropertyMetadata(null); // or omit default to inherit base metadata default
Defensive patterns

Strategy: validation

Validate before calling

if (candidate == DependencyProperty.UnsetValue)
    candidate = null; // or skip setting a default entirely to inherit the base default
var meta = new PropertyMetadata(candidate);

Type guard

static bool IsValidDefaultValue(object v) => v != DependencyProperty.UnsetValue;

Try / catch

try
{
    metadata.DefaultValue = value;
}
catch (ArgumentException ex) when (ex.Message.Contains("DefaultValue"))
{
    // UnsetValue supplied; choose null or omit to inherit base default
}

Prevention

When it happens

Trigger: Setting metadata.DefaultValue = DependencyProperty.UnsetValue (or constructing PropertyMetadata with DependencyProperty.UnsetValue as its defaultValue argument), often intending to 'clear' a default.

Common situations: Trying to reset a default to 'unset' during OverrideMetadata; generic helper code that passes a value straight from a lookup which returned UnsetValue; confusion between UnsetValue and null as a default.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of dotnet/wpf@81131a70a4 (2026-09-14). Data as JSON: /api/errors/21547186d529d613. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/WindowsBase/System/Windows/PropertyMetadata.cs:97

                {
                    return _defaultValue;
                }
                else
                {
                    return defaultFactory.DefaultValue;
                }
            }

            set
            {
                if (Sealed)
                {
                    throw new InvalidOperationException(SR.TypeMetadataCannotChangeAfterUse);
                }

                if (value == DependencyProperty.UnsetValue)
                {
                    throw new ArgumentException(SR.DefaultValueMayNotBeUnset);
                }

                _defaultValue = value;

                SetModified(MetadataFlags.DefaultValueModifiedID);
            }
        }


        /// <summary>
        ///     Returns true if the default value is a DefaultValueFactory
        /// </summary>
        internal bool UsingDefaultValueFactory
        {
            get
            {
                return _defaultValue is DefaultValueFactory;
            }

View on GitHub (pinned to 81131a70a4)