dotnet/wpf · error

DocumentViewer element can have only one child.

Error message

DocumentViewer element can have only one child.

What it means

DocumentViewerBase implements IAddChild so XAML parsers can add a document as its single child. Since a DocumentViewer can host exactly one FlowDocument-family document, calling IAddChild.AddChild when Document is already set throws InvalidOperationException.

Solutions

1. Remove the extra child so only one IDocumentPaginatorSource remains inside the viewer
2. Clear/replace the Document property instead of calling AddChild to change the document
3. Wrap multiple documents in separate viewers (e.g. FlowDocumentPageViewer per document) if more content is needed

Example fix

// before
<DocumentViewer>
  <FlowDocument/><FlowDocument/>
</DocumentViewer>
// after
<DocumentViewer>
  <FlowDocument/>
</DocumentViewer>

if (viewer.Document != null) { /* replace instead of adding */ viewer.Document = newDoc; }

try { ((IAddChild)viewer).AddChild(doc); }
catch (InvalidOperationException) { /* Document already set - assign Document instead */ }

When it happens

Trigger: Declaring two document children inside a <DocumentViewer> in XAML, or calling AddChild on the viewer in code after Document (or a previous child) has been set.

Common situations: Copying a FlowDocument element inside a DocumentViewer block, or programmatically adding content without checking whether a document is already assigned.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Animation_ChildMustBeKeyFrame
• Animation_ChildMustBeKeyFrame
• Animation_NoTextChildren
• Animation_NoTextChildren
• ArgumentException: path

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Controls/Primitives/DocumentViewerBase.cs:1701

        //
        //  IAddChild
        //
        //-------------------------------------------------------------------

        #region IAddChild

        /// <summary>
        /// Called to add the object as a Child.
        /// </summary>
        /// <param name="value">Object to add as a child.</param>
        /// <remarks>DocumentViewerBase only supports a single child of type IDocumentPaginatorSource.</remarks>
        void IAddChild.AddChild(Object value)
        {
            ArgumentNullException.ThrowIfNull(value);
            // Check if Content has already been set.
            if (this.Document != null)
            {
                throw new InvalidOperationException(SR.DocumentViewerCanHaveOnlyOneChild);
            }
            // Only IDocumentPaginatorSource is a valid content.
            IDocumentPaginatorSource document = value as IDocumentPaginatorSource;
            if (document == null)
            {
                throw new ArgumentException(SR.DocumentViewerChildMustImplementIDocumentPaginatorSource, nameof(value));
            }
            this.Document = document;
        }

        /// <summary>
        /// Called when text appears under the tag in markup
        /// </summary>
        /// <param name="text">Text to add to the Object.</param>
        /// <remarks>DocumentViewer does not support Text children.</remarks>
        void IAddChild.AddText(string text)
        {
            XamlSerializerUtil.ThrowIfNonWhiteSpaceInAddText(text, this);

View on GitHub (pinned to 81131a70a4)