What causes "SR.VisualCollection_NotEnoughCapacity" in dotnet/wpf?

Remove children first (Clear/Remove) until Count <= desired capacity, then set Capacity.

dotnet/wpf · error · ArgumentOutOfRangeException

SR.VisualCollection_NotEnoughCapacity

Error message

SR.VisualCollection_NotEnoughCapacity

What it means

Thrown by the VisualCollection.Capacity property setter when the requested capacity is smaller than the current number of items in the collection (_size). Capacity cannot shrink below Count because existing children would be lost.

Solutions

Remove children first (Clear/Remove) until Count <= desired capacity, then set Capacity.
Set Capacity to at least collection.Count: Capacity = Math.Max(desired, collection.Count).
Skip the capacity adjustment when Count already exceeds the target.
Consider using TrimToSize-style patterns: only lower capacity when Count == 0.

Example fix

// before
visualCollection.Clear();
AddMoreVisuals(visualCollection, 10);
visualCollection.Capacity = 5; // ArgumentOutOfRangeException: needs >= 10
// after
visualCollection.Capacity = Math.Max(5, visualCollection.Count);

Defensive patterns

Strategy: validation

Validate before calling

int desired = 5;
if (desired >= visualCollection.Count)
    visualCollection.Capacity = desired;

Type guard

static bool CanSetCapacity(VisualCollection c, int value) => value >= c.Count;

Try / catch

try { collection.Capacity = value; }
catch (ArgumentOutOfRangeException) { /* value < Count; clamp or clear first */ }

Prevention

Always clamp capacity to Math.Max(desired, collection.Count).
Clear the collection before aggressively shrinking capacity.
Recalculate capacity from Count rather than stale constants.

When it happens

Trigger: Setting collection.Capacity to a value less than collection.Count, e.g. after adding children then trying Capacity = 0 or Capacity = oldCapacity while more visuals were added since.

Common situations: Pooling/optimization code that resets capacity to a constant without checking Count; trimming memory after reparenting visuals into the collection.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/Media/VisualCollection.cs:246

        }

        /// <summary>
        /// InternalCapacity sets/gets the Capacity of the collection.
        /// </summary>
        internal int InternalCapacity
        {
            get
            {
                return _items != null ? _items.Length : 0;
            }
            set
            {
                int currentCapacity = _items != null ? _items.Length : 0;
                if (value != currentCapacity)
                {
                    if (value < _size)
                    {
                        throw new ArgumentOutOfRangeException(nameof(value), SR.VisualCollection_NotEnoughCapacity);
                    }
                    if (value > 0)
                    {
                        Visual[] newItems = new Visual[value];
                        if (_size > 0)
                        {
                            Debug.Assert(_items != null);
                            Array.Copy(_items, 0, newItems, 0, _size);
                        }
                        _items = newItems;
                    }
                    else
                    {
                        Debug.Assert(value == 0, "There shouldn't be a case where value != 0.");
                        Debug.Assert(_size == 0, "Size must be 0 here.");
                        _items = null;
                    }
                }

View on GitHub (pinned to 81131a70a4)