dotnet/wpf · error · ArgumentException

SR.Format(SR.TextSchema_TheChildElementBelongsToAnotherTreeA…

Error message

SR.Format(SR.TextSchema_TheChildElementBelongsToAnotherTreeAlready, value.GetType().Name)

What it means

After validating the child type, FlowDocument.IAddChild.AddChild checks that a TextElement child is not already parented to another tree. Adding an element that already has a Parent would reparent it and corrupt the previous document, so the method throws ArgumentException with SR.TextSchema_TheChildElementBelongsToAnotherTreeAlready, including the child's type name.

Solutions

  1. Detach the child first: ((Block)value).Reposition(null, null) or remove it from its current Blocks/Inlines collection before adding
  2. Create a new element instance (or a deep clone) instead of reusing one across trees
  3. Check value is TextElement te && te.Parent is null before adding
  4. Catch ArgumentException and clone the subtree programmatically (e.g. via XamlWriter/XamlReader round-trip)

Example fix

// before
doc2.Blocks.Add(sharedParagraph); // throws if sharedParagraph.Parent != null
// after
if (sharedParagraph.Parent is BlockCollection bc) bc.Remove(sharedParagraph);
doc2.Blocks.Add(sharedParagraph);
Defensive patterns

Strategy: validation

Validate before calling

if (value is System.Windows.Documents.TextElement te && te.Parent != null)
    throw new ArgumentException($"{te.GetType().Name} already belongs to another tree; detach or clone first.");

Type guard

bool CanAddToTree(System.Windows.Documents.TextElement el) => el.Parent is null;

Try / catch

try { doc.Blocks.Add(block); }
catch (ArgumentException) {
    block.Reposition(null, null); // detach
    doc.Blocks.Add(block);
}

Prevention

When it happens

Trigger: Calling IAddChild.AddChild (or Blocks.Add / Inlines.Add) with a TextElement (Paragraph, Run, Section...) whose Parent is non-null — i.e. the same element instance is being inserted into a second document or a second location.

Common situations: Reusing a Paragraph/Run instance across two FlowDocuments; cloning UI templates that share element instances; moving a Block between documents without detaching it first (e.g. in copy/paste or template code).

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Documents/FlowDocument.cs:1632

        ///<summary>
        /// Called to Add the object as a Child.
        ///</summary>
        ///<param name="value">
        /// Object to add as a child
        ///</param>
        void IAddChild.AddChild(Object value)
        {
            ArgumentNullException.ThrowIfNull(value);

            if (!TextSchema.IsValidChildOfContainer(/*parentType:*/_typeofThis, /*childType:*/value.GetType()))
            {
                throw new ArgumentException(SR.Format(SR.TextSchema_ChildTypeIsInvalid, _typeofThis.Name, value.GetType().Name));
            }

            // Checking that the element inserted does not have a parent
            if (value is TextElement && ((TextElement)value).Parent != null)
            {
                throw new ArgumentException(SR.Format(SR.TextSchema_TheChildElementBelongsToAnotherTreeAlready, value.GetType().Name));
            }

            if (value is Block)
            {
                TextContainer textContainer = _structuralCache.TextContainer;
                ((Block)value).RepositionWithContent(textContainer.End);
            }
            else
            {
                Invariant.Assert(false); // We do not expect anything except Blocks on top level of a FlowDocument
            }
        }

        ///<summary>
        /// Called when text appears under the tag in markup
        ///</summary>
        ///<param name="text">
        /// Text to Add to the Object

View on GitHub (pinned to 81131a70a4)