dotnet/wpf · error · InvalidOperationException

SR.Format(SR.TextElementCollection_NextSiblingDoesNotBelongT…

Error message

SR.Format(SR.TextElementCollection_NextSiblingDoesNotBelongToThisCollection, nextSibling.GetType().Name)

What it means

Thrown by TextElementCollection<T>.InsertBefore as an InvalidOperationException when the nextSibling reference does not belong to this collection: its Parent differs from the collection's Parent. InsertBefore inserts relative to a sibling, so the anchor must already live in the same parent element.

Solutions

Use a nextSibling whose Parent equals this collection's Parent object.
If the anchor is unattached, insert it first (Add) or compute a different insertion position (e.g. use TextPointer-based insertion).
Verify you are calling InsertBefore on the collection of the same parent that owns nextSibling.

Example fix

// before
wrongParagraph.Inlines.InsertBefore(runInOtherPara, newRun);
// after
var host = (Paragraph)runInOtherPara.Parent;
host.Inlines.InsertBefore(runInOtherPara, newRun);

Defensive patterns

Strategy: validation

Validate before calling

if (nextSibling != null && nextSibling.Parent == collection.Parent)
    collection.InsertBefore(nextSibling, newItem);

Type guard

bool AnchorIsValid(TextElementType anchor, object collectionParent) => anchor?.Parent == collectionParent;

Try / catch

try { collection.InsertBefore(anchor, item); }
catch (InvalidOperationException ex) when (ex.Message.Contains("does not belong")) { /* pick an anchor owned by this parent */ }

Prevention

Derive the anchor from the same parent you are inserting into ((T)anchor.Parent).
Never hold anchor references across container boundaries.
Re-query the anchor after any structural change to the tree.

When it happens

Trigger: Calling InsertBefore(nextSibling, newItem) where nextSibling.Parent != this.Parent — e.g. the anchor element is a child of a different Paragraph/TextElement or is unparented (null).

Common situations: Passing an anchor run from another paragraph; passing an element that was just removed from the collection; mixing up which container owns the anchor.

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/d8c6fb7d20a10097. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Documents/TextElementCollection.cs:287

        /// <summary>
        /// Inserts a TextElement newItem into a collection before a nextSibling TextElement.
        /// </summary>
        /// <param name="nextSibling">
        /// TextElement before which the newItem is to be inserted
        /// </param>
        /// <param name="newItem">
        /// A TextElement to be inserted into the collection before the nextSibling.
        /// It must be unlinked from a tree before insertion.
        /// </param>
        public void InsertBefore(TextElementType nextSibling, TextElementType newItem)
        {
            ArgumentNullException.ThrowIfNull(nextSibling);

            ArgumentNullException.ThrowIfNull(newItem);

            if (nextSibling.Parent != this.Parent)
            {
                throw new InvalidOperationException(SR.Format(SR.TextElementCollection_NextSiblingDoesNotBelongToThisCollection, nextSibling.GetType().Name));
            }

            if (newItem.Parent != null)
            {
                throw new ArgumentException(SR.Format(SR.TextSchema_TheChildElementBelongsToAnotherTreeAlready, this.GetType().Name));
            }

            ValidateChild(newItem);

            this.TextContainer.BeginChange();
            try
            {
                newItem.RepositionWithContent(nextSibling.ElementStart);
            }
            finally
            {
                this.TextContainer.EndChange();
            }

View on GitHub (pinned to 81131a70a4)