dotnet/wpf · error · InvalidOperationException

SR.PrevoiusUninitializedDocumentReferenceOutstanding

Error message

SR.PrevoiusUninitializedDocumentReferenceOutstanding

What it means

DocumentSequence.AddChild tracks one partially-initialized DocumentReference (_partialRef) at a time, waiting for its Initialized event before accepting the next child. If a previous DocumentReference is still uninitialized when AddChild is called again, it throws InvalidOperationException with SR.PrevoiusUninitializedDocumentReferenceOutstanding.

Solutions

Fully initialize each DocumentReference (set Document or a resolvable Source) before adding the next one
Wait for the previous DocumentReference's Initialized event before calling AddChild again
Use data binding / the standard XAML DocumentReference pattern instead of manual AddChild
Check that the earlier reference's Source is valid so initialization can complete

Example fix

// before
foreach (var doc in docs) { seq.AddChild(doc); } // refs not initialized
// after
foreach (var doc in docs)
{
    if (!doc.IsInitialized) doc.Document = ResolveDocument(doc);
    seq.AddChild(doc);
}

Defensive patterns

Strategy: validation

Validate before calling

if (pendingRef != null && !pendingRef.IsInitialized) throw new InvalidOperationException("Previous DocumentReference not initialized");

Try / catch

try { seq.AddChild(docRef); } catch (InvalidOperationException ex) { log.Error("Outstanding uninitialized DocumentReference", ex); }

Prevention

Fully initialize (set Document or Source) each reference before adding the next
Subscribe to Initialized and add sequentially in the handler
Prefer standard XAML patterns over manual AddChild

When it happens

Trigger: Adding a second DocumentReference while the first has not yet been initialized (its Source/Id not resolved and Initialized event not fired) — e.g. rapid programmatic AddChild calls without setting up each reference fully, or malformed markup that skips initialization.

Common situations: Programmatically adding many DocumentReferences in a loop without assigning each one's Document/Source; a reference whose Source fails to resolve leaving the pending state stuck; unusual parsing scenarios where initialization callbacks are deferred.

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

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Documents/DocumentSequence.cs:118

            {
                throw new ArgumentException(SR.Format(SR.UnexpectedParameterType, value.GetType(), typeof(DocumentReference)), nameof(value));
            }

            if (docRef.IsInitialized)
            {
                _references.Add(docRef);
            }
            else
            {
                DocumentsTrace.FixedDocumentSequence.Content.Trace($"Doc {_references.Count} Deferred");
                if (_partialRef == null)
                {
                    _partialRef = docRef;
                    _partialRef.Initialized += new EventHandler(_OnDocumentReferenceInitialized);
                }
                else
                {
                    throw new InvalidOperationException(SR.PrevoiusUninitializedDocumentReferenceOutstanding);
                }
            }
        }

        ///<summary>
        /// Called when text appears under the tag in markup
        ///</summary>
        ///<param name="text">
        /// Text to Add to the Object
        ///</param>
        void IAddChild.AddText(string text)
        {
            XamlSerializerUtil.ThrowIfNonWhiteSpaceInAddText(text, this);
        }

        #endregion

        #region IFixedNavigate

View on GitHub (pinned to 81131a70a4)