dotnet/wpf · error · ArgumentException

SR.Format(SR.TextElementCollection_TextElementTypeExpected…

Error message

SR.Format(SR.TextElementCollection_TextElementTypeExpected, typeof(TextElementType).Name)

What it means

Thrown by the internal virtual OnAdd (reached via Add / IList.Add) when the value being added is not an instance of the collection's TextElementType. Non-generic IList.Add accepts object, so the runtime type is validated here.

Solutions

Add only objects of the collection's element type (e.g. Paragraph for BlockCollection, Run for InlineCollection).
Create a compatible element wrapping the content instead of adding the raw object.
Compile-time: prefer the strongly typed Add overload / collection<T> API rather than IList.Add.

Example fix

// before
IList blocks = flowDocument.Blocks;
blocks.Add("hello"); // string, not a Block
// after
blocks.Add(new Paragraph(new Run("hello")));

Defensive patterns

Strategy: type-guard

Validate before calling

if (value is TextElementType te)
    collection.Add(te);

Type guard

static bool IsElementType(object value) => value is TextElementType;

Try / catch

try { ((IList)collection).Add(value); }
catch (ArgumentException ex) when (ex.Message.Contains("expected")) { /* construct a compatible TextElement and retry */ }

Prevention

Use the strongly typed collection API instead of IList.Add.
Know each collection's element type (BlockCollection->Block, InlineCollection->Inline, ListItemCollection->ListItem).
Wrap plain content (strings, controls) in the proper TextElement before adding.

When it happens

Trigger: Calling Add(value) or IList.Add on the collection with an object not assignable to TextElementType (e.g. adding a string or a Run to a ListItemCollection).

Common situations: Non-generic collection APIs used via IList; data binding or reflection feeding arbitrary objects; wrong collection/element pairing in code-built FlowDocuments.

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

Appendix: source

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

        //...................................................................
        //
        //  IList Members
        //
        //...................................................................

        #region IList Members

        /// <summary>
        /// Method that does the work for IList.Add.
        /// </summary>
        internal virtual int OnAdd(object value)
        {
            ArgumentNullException.ThrowIfNull(value);

            if (!(value is TextElementType))
            {
                throw new ArgumentException(SR.Format(SR.TextElementCollection_TextElementTypeExpected, typeof(TextElementType).Name), nameof(value));
            }

            ValidateChild((TextElementType)value);

            this.TextContainer.BeginChange();
            try
            {
                bool isCacheSafePreviousIndex = _indexCache.IsValid(this);

                this.Add((TextElementType)value);

                return IndexOfInternal(value, isCacheSafePreviousIndex);
            }
            finally
            {
                this.TextContainer.EndChange();
            }
        }

View on GitHub (pinned to 81131a70a4)