dotnet/wpf · error · ArgumentOutOfRangeException

SR.Visual_ArgumentOutOfRange

Error message

SR.Visual_ArgumentOutOfRange

What it means

An internal single-child visual wrapper used by KeyboardNavigation implements GetVisualChild and only supports index 0 (its adorner child). Any other index throws ArgumentOutOfRangeException with SR.Visual_ArgumentOutOfRange. It surfaces from MeasureOverride/ArrangeOverride while WPF enumerates visual children, and usually indicates the visual tree around keyboard navigation got corrupted or an internal invariant broke.

Solutions

1. Avoid mutating the visual tree (Add/RemoveVisualChild, adorners) during Measure/Arrange; defer changes to the dispatcher (Dispatcher.BeginInvoke) or the Loaded/LayoutUpdated-after pass.
2. Check your code for reflection/VisualTreeHelper access into KeyboardNavigation internals and remove it.
3. If reproducible without such code, it is a WPF framework bug: reduce to a minimal repro and check/report against your .NET runtime version (try the latest servicing release).
4. Catch the exception at the layout boundary only as a diagnostic aid, then fix the tree-mutation timing.

Example fix

// before (mutating tree inside measure)
private void OnMeasure(object s, EventArgs e) { panel.Children.Remove(marker); }

// after (defer tree mutation)
private void OnMeasure(object s, EventArgs e)
{
    Dispatcher.BeginInvoke(() => panel.Children.Remove(marker), System.Windows.Threading.DispatcherPriority.Loaded);
}

try { element.Measure(availableSize); }
catch (ArgumentOutOfRangeException ex) when (ex.Message.Contains("Visual"))
{ // log visual-tree corruption details and rebuild the affected subtree
  RebuildVisualTree(element); }

When it happens

Trigger: Layout (Measure/Arrange) enumerating the children of this internal wrapper with an index > 0; third-party code poking at Visual children via reflection or VisualTreeHelper on the internal wrapper; a corrupted visual tree after removing/reparenting elements mid-layout.

Common situations: Complex adorner/keyboard-navigation scenarios combined with elements added or removed during the LayoutUpdated/Measure pass; framework-level bugs in specific .NET/WPF versions; aggressive visual-tree manipulation in automation or theme-switching code.

Related errors

• SR.Stack_VisualInDifferentSubTree
• ' ' is not a Visual or Visual3D.
• 0x80040206
• Argument out of range (position not contained in view)
• ArgumentNullException: child

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Input/KeyboardNavigation.cs:664

            /// <summary>
            ///   Derived class must implement to support Visual children. The method must return
            ///    the child at the specified index. Index must be between 0 and GetVisualChildrenCount-1.
            ///
            ///    By default a Visual does not have any children.
            ///
            ///  Remark:
            ///       During this virtual call it is not valid to modify the Visual tree.
            /// </summary>
            protected override Visual GetVisualChild(int index)
            {
                if (index == 0)
                {
                    return _adorderChild;
                }
                else
                {
                    throw new ArgumentOutOfRangeException(nameof(index), index, SR.Visual_ArgumentOutOfRange);
                }
            }

            private IContentHost ContentHost
            {
                get
                {
                    // Re-query IContentHost if the old one was disposed
                    if (_adornedContentElement != null && (_contentHostParent==null || VisualTreeHelper.GetParent(_contentHostParent as Visual) == null))
                    {
                        _contentHostParent = MS.Internal.Documents.ContentHostHelper.FindContentHost(_adornedContentElement);
                    }

                    return _contentHostParent;
                }
            }

            /// <summary>

View on GitHub (pinned to 81131a70a4)