dotnet/wpf · error · ArgumentException

SR.OverridingMetadataDoesNotMatchBaseMetadataType

Error message

SR.OverridingMetadataDoesNotMatchBaseMetadataType

What it means

When overriding metadata, the new metadata's type must be the same as, or derived from, the base metadata's type. You cannot replace a specialized metadata (e.g. FrameworkPropertyMetadata) with a less-derived one (e.g. PropertyMetadata), because that would drop behavior the property system relies on.

Solutions

1. Use the same metadata type as the base (typically FrameworkPropertyMetadata for UI element properties).
2. Derive your override metadata type from the base metadata type rather than from PropertyMetadata.
3. Inspect the base property's DefaultMetadata type to determine the correct class to use.

Example fix

// before
MyProperty.OverrideMetadata(typeof(MyControl), new PropertyMetadata(false));
// after
MyProperty.OverrideMetadata(typeof(MyControl),
    new FrameworkPropertyMetadata(false, FrameworkPropertyMetadataOptions.AffectsRender));

var baseMeta = dp.GetMetadata(typeof(BaseType));
if (!baseMeta.GetType().IsAssignableFrom(newMeta.GetType())) throw new ArgumentException("Override metadata type must derive from base metadata type");

static bool IsCompatibleMetadata(DependencyProperty dp, Type forType, PropertyMetadata m) => dp.GetMetadata(forType.BaseType).GetType().IsAssignableFrom(m.GetType());

When it happens

Trigger: Calling OverrideMetadata with new PropertyMetadata(...) on a property whose base metadata is FrameworkPropertyMetadata; also overriding with a metadata type from an unrelated hierarchy.

Common situations: Copy-pasting a generic PropertyMetadata override for a UI property declared with FrameworkPropertyMetadata; writing helper methods that always construct plain PropertyMetadata.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• SR.TypeMetadataAlreadyInUse
• Animation_CalculatedValueIsInvalidForProperty
• Animation_DependencyPropertyIsNotAnimatable
• Image_EncoderNoGlobalMetadata
• Image_MetadataNotCompatible

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/WindowsBase/System/Windows/DependencyProperty.cs:482

            // otherwise, the default value will be taken from the base metadata
            // which was already validated)
            if (typeMetadata.IsDefaultValueModified)
            {
                // Will throw ArgumentException if fails.
                ValidateMetadataDefaultValue( typeMetadata, PropertyType, Name, ValidateValueCallback );
            }

            // Force all base classes to register their metadata
            dType = DependencyObjectType.FromSystemType(forType);

            // Get metadata for the base type
            baseMetadata = GetMetadata(dType.BaseType);

            // Make sure overriding metadata is the same type or derived type of
            // the base metadata
            if (!baseMetadata.GetType().IsAssignableFrom(typeMetadata.GetType()))
            {
                throw new ArgumentException(SR.OverridingMetadataDoesNotMatchBaseMetadataType);
            }
        }


        /// <summary>
        ///     Supply metadata for given type & run static constructors if needed.
        /// </summary>
        /// <remarks>
        ///     The supplied metadata will be merged with the type's base
        ///     metadata
        /// </remarks>
        public void OverrideMetadata(Type forType, PropertyMetadata typeMetadata)
        {
            DependencyObjectType dType;
            PropertyMetadata baseMetadata;

            SetupOverrideMetadata(forType, typeMetadata, out dType, out baseMetadata);

View on GitHub (pinned to 81131a70a4)