dotnet/wpf · error · ArgumentException

SR.TreeScopeElementChildrenDescendantsOnly

Error message

SR.TreeScopeElementChildrenDescendantsOnly

What it means

The CacheRequest.TreeScope property setter only accepts Element, Children, and Descendants bits. Any other TreeScope flag (e.g. Parent, Ancestors, Subtree) makes the masked value non-zero and throws ArgumentException, because UI Automation caching cannot traverse upward or to the root.

Solutions

  1. Use only TreeScope.Element, TreeScope.Children, and TreeScope.Descendants (or combinations of those)
  2. Replace TreeScope.Subtree with TreeScope.Element | TreeScope.Children | TreeScope.Descendants
  3. Strip upward-scope bits before assignment: scope &= ~(TreeScope.Parent | TreeScope.Ancestors)
  4. For ancestor data, issue separate element navigation (TreeWalker) instead of caching upward

Example fix

// before
request.TreeScope = TreeScope.Subtree; // throws
// after
request.TreeScope = TreeScope.Element | TreeScope.Children | TreeScope.Descendants;
Defensive patterns

Strategy: validation

Validate before calling

const TreeScope allowed = TreeScope.Element|TreeScope.Children|TreeScope.Descendants;
scope &= allowed; if (scope == 0) scope = TreeScope.Element;

Type guard

bool IsCacheableScope(TreeScope s) => (s & ~(TreeScope.Element|TreeScope.Children|TreeScope.Descendants)) == 0 && s != 0;

Try / catch

try { request.TreeScope = scope; } catch (ArgumentException) { request.TreeScope = TreeScope.Element|TreeScope.Children; }

Prevention

When it happens

Trigger: Assigning TreeScope.Subtree (which includes Ancestors), TreeScope.Parent, TreeScope.Ancestors, or any combination containing those bits to CacheRequest.TreeScope.

Common situations: Reusing TreeScope values intended for other UIA APIs (like Find with Subtree) in a CacheRequest; a generic scope picker in UI code that offers Parent/Ancestors options; converting between legacy TreeScope constants.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/UIAutomation/UIAutomationClient/System/Windows/Automation/CacheRequest.cs:308

        /// TreeScope.Parent and TreeScope.Ancestors are not supported.
        /// </remarks>
        public TreeScope TreeScope
        {
            get
            {
                return _scope;
            }
            
            set
            {
                if (value == 0)
                {
                    throw new ArgumentException(SR.TreeScopeNeedAtLeastOne);
                }

                if ((value & ~(TreeScope.Element | TreeScope.Children | TreeScope.Descendants)) != 0)
                {
                    throw new ArgumentException(SR.TreeScopeElementChildrenDescendantsOnly);
                }

                lock (_instanceLock)
                {
                    CheckAccess();
                    if (_scope != value)
                    {
                        _scope = value;
                        Invalidate();
                    }
                }
            }
        }


        /// <summary>
        /// Indicates the view to use when prefetching relative nodes
        /// </summary>

View on GitHub (pinned to 81131a70a4)