What causes "Expected DOCUMENT-END." in stride3d/stride?

Emit a DocumentEnd event after each document's node before starting the next

stride3d/stride · error · YamlException

Expected DOCUMENT-END.

Error message

Expected DOCUMENT-END.

What it means

The emitter's state machine was in a document context and expected a DOCUMENT-END event, but received something else. Emitter.EmitDocumentEndContent throws when the current event is not DocumentEnd, meaning documents were not properly terminated before starting new content.

Solutions

Emit a DocumentEnd event after each document's node before starting the next
Ensure every Emit(DocumentStart) has a matching Emit(DocumentEnd)
Restart emission with a new Emitter after an error instead of continuing the broken state machine
Audit the event-producing loop for missing end events

Example fix

// before
emitter.Emit(docStart2); // previous document still open
// after
emitter.Emit(new DocumentEnd(true, null, null));
emitter.Emit(docStart2);

Defensive patterns

Strategy: try-catch

Validate before calling

// track expected state before each Emit
bool expectDocEnd = documentOpen;
if (expectDocEnd && evt.Type != EventType.YAML_DOCUMENT_END_EVENT) throw new InvalidOperationException("Emit DocumentEnd first");

Try / catch

try { emitter.Emit(evt); }
catch (YamlException ex) when (ex.Message.Contains("Expected DOCUMENT-END")) { /* emit DocumentEnd, then re-queue the event */ }

Prevention

Pair every DocumentStart with a DocumentEnd in the same code path
Use try/finally to guarantee DocumentEnd on failures
Avoid interleaving events from multiple documents into one emitter

When it happens

Trigger: Emitting a second DocumentStart or node event while the emitter still awaits DocumentEnd for the previous document; feeding StreamEnd without closing the open document.

Common situations: Multi-document emission loops that forget to call Emit(new DocumentEnd(...)) per document; exception-recovery paths that skip the end event; merging event streams from multiple sources.

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 stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/3854fc576e49c33a. Report an issue: GitHub.

Appendix: source

Thrown at sources/core/Stride.Core.Yaml/Emitter.cs:1563

        private void EmitDocumentEnd(ParsingEvent evt)
        {
            DocumentEnd documentEnd = evt as DocumentEnd;
            if (documentEnd != null)
            {
                WriteIndent();
                if (!documentEnd.IsImplicit)
                {
                    WriteIndicator("...", true, false, false);
                    WriteIndent();
                }

                state = EmitterState.YAML_EMIT_DOCUMENT_START_STATE;

                tagDirectives.Clear();
            }
            else
            {
                throw new YamlException("Expected DOCUMENT-END.");
            }
        }

        /// <summary>
        /// 
        /// Expect a flow item node.
        /// </summary>
        private void EmitFlowSequenceItem(ParsingEvent evt, bool isFirst)
        {
            if (isFirst)
            {
                WriteIndicator("[", true, true, false);
                IncreaseIndent(true, false);
                ++flowLevel;
            }

            if (evt is SequenceEnd)
            {

View on GitHub (pinned to 96fad776d2)