dotnet/wpf · error · InvalidOperationException

SR.Format(SR.NamedObjectMustBeFrameworkElement, targetName)

Error message

SR.Format(SR.NamedObjectMustBeFrameworkElement, targetName)

What it means

FindNamedFrameworkElement resolves a registered name (x:Name/Name) to a FrameworkElement during template or name-scope lookup. If the object registered under targetName exists but is not a FrameworkElement (e.g. a Freezable or other DependencyObject), the lookup cannot return it and throws InvalidOperationException. WPF requires named template targets used as element targets to be actual FrameworkElements.

Solutions

1. Rename the offending resource so the targetName points at an actual FrameworkElement (Control, Panel, etc.)
2. If you need the non-element object, look it up via FindResource/TryFindResource instead of name-scope element lookup
3. Move the named resource out of the template's name scope or use x:Key with a ResourceDictionary instead of x:Name
4. Cast defensively: var fe = FindName(n) as FrameworkElement; if (fe == null) handle non-element case

Example fix

// before
<LinearGradientBrush x:Name="bg" .../>
var target = (FrameworkElement)template.FindName("bg", templatedParent);
// after
<Border x:Name="bg" Background="..."/>
var target = (FrameworkElement)template.FindName("bg", templatedParent);

object named = nameScope.FindName(targetName);
if (named is not FrameworkElement) throw new InvalidOperationException($"{targetName} must be a FrameworkElement");

bool IsNamedFrameworkElement(object o) => o is FrameworkElement;

try { var fe = FindNamedFrameworkElement(nameScope, targetName); }
catch (InvalidOperationException) { /* name resolves to non-element; fall back to FindResource */ }

When it happens

Trigger: Calling FindName-related template APIs (e.g. FrameworkTemplate.FindName, TemplateContent lookup) with a targetName that resolves to a non-FrameworkElement DependencyObject in the name scope.

Common situations: x:Name placed on a non-element resource like a Brush, Geometry, or storyboard child inside a template; referencing a named Freezable from TemplateBinding/templated-parent code; name registered by parser on a value-type resource.

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

• Animation_Invalid_DefaultValue
• Cannot remove signature from read-only file.
• Image_EncoderNoColorContext
• Image_EncoderNoGlobalMetadata
• Image_EncoderNoGlobalThumbnail

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/FrameworkElement.cs:487

            else
            {
                DependencyObject targetObject = null;

                targetObject = LogicalTreeHelper.FindLogicalNode( startElement, targetName );

                if( targetObject == null )
                {
                    throw new ArgumentException( SR.Format(SR.TargetNameNotFound, targetName));
                }

                FrameworkObject fo = new FrameworkObject(targetObject);
                if( fo.IsFE )
                {
                    targetFE = fo.FE;
                }
                else
                {
                    throw new InvalidOperationException(SR.Format(SR.NamedObjectMustBeFrameworkElement, targetName));
                }
            }

            return targetFE;
        }

        /// <summary>
        ///     Triggers associated with this object.  Both the triggering condition
        /// and the trigger effect may be on this object or on its tree child
        /// objects.
        /// </summary>
        [DesignerSerializationVisibility(DesignerSerializationVisibility.Content)]
        public TriggerCollection Triggers
        {
            get
            {
                TriggerCollection triggerCollection = EventTrigger.TriggerCollectionField.GetValue(this);
                if (triggerCollection == null)

View on GitHub (pinned to 81131a70a4)