dotnet/wpf · error · ArgumentException

SR.TreeScopeNeedAtLeastOne

Error message

SR.TreeScopeNeedAtLeastOne

What it means

The CacheRequest.TreeScope property setter rejects a value of 0 (TreeScope.None). A cache request must target at least one part of the automation tree (the element itself, its children, or its descendants), so a zero scope is meaningless and throws ArgumentException.

Solutions

  1. Assign a scope that includes at least TreeScope.Element, TreeScope.Children, or TreeScope.Descendants
  2. Validate computed scope values before assignment and fall back to TreeScope.Element if the combined value is 0
  3. Guard user/config-driven scope values with a check for 0

Example fix

// before
request.TreeScope = (TreeScope)flags; // flags == 0 -> ArgumentException
// after
if ((TreeScope)flags == 0) flags = TreeScope.Element;
request.TreeScope = (TreeScope)flags;
Defensive patterns

Strategy: validation

Validate before calling

if (scope == 0) scope = TreeScope.Element;
request.TreeScope = scope;

Type guard

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

Try / catch

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

Prevention

When it happens

Trigger: Assigning (TreeScope)0 or TreeScope.None to CacheRequest.TreeScope before or after activating the request.

Common situations: Computing scope flags dynamically from booleans and having all flags evaluate false; passing an unset/zero enum field into TreeScope; serializing/deserializing settings where scope defaulted to 0.

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

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

Appendix: source

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

        /// </summary>
        /// <remarks>
        /// At least one or more of of TreeScope.Element, TreeScope.Children or
        /// TreeScope.Descendants must be specified.
        /// 
        /// 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();
                    }
                }
            }
        }

View on GitHub (pinned to 81131a70a4)