dotnet/wpf · error · InvalidOperationException

SR.MustBeFrameworkDerived

Error message

SR.MustBeFrameworkDerived

What it means

FrameworkObject wraps a DependencyObject as either a FrameworkElement or FrameworkContentElement; when neither applies and the caller asked to throw (throwIfNeither), it throws this InvalidOperationException. WPF logical-tree APIs require framework-level objects; plain DependencyObjects (e.g. Freezables or bare DependencyObjects) cannot participate.

Solutions

1. Only pass FrameworkElement or FrameworkContentElement instances to framework-tree APIs
2. For non-framework DependencyObjects, operate on them directly instead of via FrameworkObject
3. Check the type first: if (obj is FrameworkElement fe) ... else if (obj is FrameworkContentElement fce) ...
4. Guard against null before calling

Example fix

// before
var fo = new FrameworkObject(depObj, true);
// after
if (depObj is FrameworkElement || depObj is FrameworkContentElement)
{ var fo = new FrameworkObject(depObj, true); }

if (d != null && !(d is FrameworkElement) && !(d is FrameworkContentElement)) throw new InvalidOperationException("Requires FrameworkElement/ContentElement");

static bool IsFrameworkObject(DependencyObject d) => d is FrameworkElement || d is FrameworkContentElement;

try { var fo = new FrameworkObject(d, true); } catch (InvalidOperationException) { /* handle non-framework DependencyObject */ }

When it happens

Trigger: Constructing FrameworkObject with throwIfNeither:true for a DependencyObject that is neither a FrameworkElement nor FrameworkContentElement (or for null).

Common situations: Passing a Freezable (Brush, Geometry), Animation, or a plain DependencyObject to APIs that walk the logical tree; calling tree-walking helpers on non-framework nodes; accidentally passing null.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• ' ' is not a Visual or Visual3D.
• ' ' must be the root element of a tree, but has a logical…
• 0x80070057
• Animation_AnimationTimelineTypeMismatch
• Property data must be a non-reference variant compatible…

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/MS/Internal/FrameworkObject.cs:66

    {
        #region Constructors

        internal FrameworkObject(DependencyObject d)
        {
            // [code should be identical to Reset(d)]
            _do = d;

            _fe = d as FrameworkElement;
            _fce = d as FrameworkContentElement;
        }

        internal FrameworkObject(DependencyObject d, bool throwIfNeither)
            : this(d)
        {
            if (throwIfNeither && _fe == null && _fce == null)
            {
                object arg = (d != null) ? (object)d.GetType() : (object)"NULL";
                throw new InvalidOperationException(SR.Format(SR.MustBeFrameworkDerived, arg));
            }
        }

        internal FrameworkObject(FrameworkElement fe, FrameworkContentElement fce)
        {
            _fe = fe;
            _fce = fce;

            if (fe != null)
                _do = fe;
            else
                _do = fce;
        }

        internal void Reset(DependencyObject d)
        {
            _do = d;

View on GitHub (pinned to 81131a70a4)