dotnet/wpf · error · InvalidOperationException

SR.Format(SR.MustBeFrameworkDerived, d.GetType())

Error message

SR.Format(SR.MustBeFrameworkDerived, d.GetType())

What it means

StyleHelper's framework-element/content-element extraction helper throws when a DependencyObject is neither FrameworkElement, FrameworkContentElement, nor Visual3D and the caller required one of those (throwIfNeither). WPF styling can only be applied to these kinds of objects, so anything else is rejected.

Solutions

1. Ensure the object derives from FrameworkElement or FrameworkContentElement (or Visual3D) before invoking styling APIs
2. Check the object type with a guard before calling, e.g. d is FrameworkElement || d is FrameworkContentElement || d is Visual3D
3. If the intent was non-throwing, use the overload/path with throwIfNeither=false
4. Move custom logic off DependencyObject to FrameworkElement to get styling support

Example fix

// before
StyleHelper.FindTemplateChildInStyle(..., (DependencyObject)new Freezable(), ...); // throws
// after
if (d is FrameworkElement fe || d is FrameworkContentElement fce || d is Visual3D v3d)
    StyleHelper.FindTemplateChildInStyle(..., d, ...);

bool IsStyleable(DependencyObject d) =>
    d is FrameworkElement || d is FrameworkContentElement || d is Visual3D;

bool IsStyleable(DependencyObject d) => d is FrameworkElement fe || d is FrameworkContentElement fce || d is System.Windows.Media.Media3D.Visual3D v;

try { ResolveTemplateChild(d); } catch (InvalidOperationException ex) when (ex.Message.Contains("Framework")) { Log(d.GetType().FullName + " is not styleable"); }

When it happens

Trigger: Calling the FindTemplateChildInStyle / templated-parent helpers with a raw DependencyObject (e.g. DependencyObject, Freezable, or a plain Visual) that is not FrameworkElement/FrameworkContentElement/Visual3D.

Common situations: Custom framework code walking visual trees that includes non-FE leaves (adorners' internals, raw Drawings); passing a Freezable resource where an element is expected; library code bridging to StyleHelper with the wrong node type.

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.
• 0x80070057
• Animation_AnimationTimelineTypeMismatch
• Property data must be a non-reference variant compatible…
• Property is not a valid instance of PrintTicket.

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/StyleHelper.cs:2334

        // to handle Visual3D (workaround for PDC)

        internal static void SpecialDowncastToFEorFCE(DependencyObject d,
                                    out FrameworkElement fe, out FrameworkContentElement fce,
                                    bool throwIfNeither)
        {
            if (d is FrameworkElement frameworkElement)
            {
                fe = frameworkElement;
                fce = null;
            }
            else if (d is FrameworkContentElement frameworkContentElement)
            {
                fe = null;
                fce = frameworkContentElement;
            }
            else if (throwIfNeither && !(d is System.Windows.Media.Media3D.Visual3D) )
            {
                throw new InvalidOperationException(SR.Format(SR.MustBeFrameworkDerived, d.GetType()));
            }
            else
            {
                fe = null;
                fce = null;
            }
        }


        #endregion ClearGeneratedSubTree

        //  ===========================================================================
        //  These methods are invoked when an Event
        //  is routed through a tree
        //  ===========================================================================

        #region InvokeEventTriggers

View on GitHub (pinned to 81131a70a4)