dotnet/wpf · error · ArgumentException

SR.ElementMustBelongToTemplate

Error message

SR.ElementMustBelongToTemplate

What it means

DependencyPropertyHelper.IsTemplatedValueDynamic determines whether a property value on an element inside a template is dynamic (resource/perf dependency). The argument must be an element that belongs to a template; if its TemplatedParent is null the element does not belong to any template, so an ArgumentException naming elementInTemplate is thrown.

Solutions

1. Pass only elements that are inside a template: check element.TemplatedParent != null before calling
2. Move up/down the tree to a child that was instantiated by the template rather than the templated control itself
3. Re-query after template application is complete (e.g. after the element is loaded and templated), not before

Example fix

// before
DependencyPropertyHelper.IsTemplatedValueDynamic(myWindow, Window.BackgroundProperty); // TemplatedParent is null
// after
if (myWindow.TemplatedParent != null)
    DependencyPropertyHelper.IsTemplatedValueDynamic(myWindow, Window.BackgroundProperty);

if (element == null || element.TemplatedParent == null)
    throw new ArgumentException("Element must belong to a template (TemplatedParent != null).");

static bool IsInTemplate(DependencyObject e) => e is FrameworkObject f ? f.TemplatedParent != null : e is FrameworkElement fe && fe.TemplatedParent != null;

try { return DependencyPropertyHelper.IsTemplatedValueDynamic(element, prop); }
catch (ArgumentException ex) when (ex.ParamName == "elementInTemplate") { /* treat as non-templated element */ }

When it happens

Trigger: Calling DependencyPropertyHelper.IsTemplatedValueDynamic(element, property) with an element whose TemplatedParent is null — e.g. a top-level window, a control created directly (not via template expansion), or an element removed from its templated parent.

Common situations: Querying the root Window/Page itself instead of a visual child inside its ControlTemplate/DataTemplate, querying elements after a template was re-applied (invalidating TemplatedParent), or passing elements from a plain visual tree that never came from templating.

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

• " }} " element found. Expected fixed page element ( }} ).
• ' ' ContentType is not valid.
• ' ' ID is not a valid XSD ID.
• array
• Cannot pass multidimensional array to the CopyTo method on…

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/DependencyPropertyHelper.cs:203

        /// </summary>
        /// <param name="elementInTemplate">element belonging to a template instance</param>
        /// <param name="dependencyProperty">property</param>
        /// <remarks>
        /// This method provides more detailed information in cases where
        /// the BaseValueSource is ParentTemplate.  The information is primarily
        /// of use to diagnostic tools.
        /// </remarks>
        public static bool IsTemplatedValueDynamic(DependencyObject elementInTemplate, DependencyProperty dependencyProperty)
        {
            ArgumentNullException.ThrowIfNull(elementInTemplate);
            ArgumentNullException.ThrowIfNull(dependencyProperty);

            FrameworkObject child = new FrameworkObject(elementInTemplate);
            DependencyObject templatedParent = child.TemplatedParent;

            if (templatedParent == null)
            {
                throw new ArgumentException(SR.ElementMustBelongToTemplate, nameof(elementInTemplate));
            }

            int templateChildIndex = child.TemplateChildIndex;
            return StyleHelper.IsValueDynamic(templatedParent, templateChildIndex, dependencyProperty);
        }
    }
}

View on GitHub (pinned to 81131a70a4)