What causes "Expected DOCUMENT-START or STREAM-END" in stride3d/stride?

Emit DocumentStart before any document content events.

stride3d/stride · error · YamlException

Expected DOCUMENT-START or STREAM-END

Error message

Expected DOCUMENT-START or STREAM-END

What it means

In the YAML_DOCUMENT_IMPLICIT_STATE the emitter expects either DocumentStart (begin a document) or StreamEnd (finish the stream). Any other event in that state throws YamlException because document content cannot start before DocumentStart.

Solutions

Emit DocumentStart before any document content events.
For multiple documents, emit DocumentEnd then a new DocumentStart per document.
After the last document emit StreamEnd instead of content events.

Example fix

// before
emitter.Emit(new StreamStart());
emitter.Emit(new Scalar("value")); // throws
// after
emitter.Emit(new StreamStart());
emitter.Emit(new DocumentStart());
emitter.Emit(new Scalar("value"));

Defensive patterns

Strategy: type-guard

Validate before calling

bool ContentAllowedAfterStreamStart(ParsingEvent evt) =>
    evt is DocumentStart || evt is StreamEnd;
// only pass content events once a DocumentStart has been emitted

Type guard

bool IsDocumentLevelEvent(ParsingEvent evt) => evt is DocumentStart or StreamEnd;

Try / catch

try { emitter.Emit(evt); }
catch (YamlException ex) when (ex.Message == "Expected DOCUMENT-START or STREAM-END") { /* insert missing DocumentStart or terminate with StreamEnd */ }

Prevention

Emit DocumentStart before any content
For multi-document streams close each with DocumentEnd and reopen with DocumentStart
Validate event sequences with a small state checker before emitting

When it happens

Trigger: Emitting a Scalar/SequenceStart/MappingStart (or DocumentEnd) directly between StreamStart and DocumentStart, or after DocumentEnd without a new DocumentStart.

Common situations: Emitting multiple documents but forgetting to open each with DocumentStart; emitting content events at stream level; event sequences generated by faulty custom producers.

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

Appendix: source

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

                    }
                }

                state = EmitterState.YAML_EMIT_DOCUMENT_CONTENT_STATE;
            }

            else if (evt is StreamEnd)
            {
                if (isOpenEnded)
                {
                    WriteIndicator("...", true, false, false);
                    WriteIndent();
                }

                state = EmitterState.YAML_EMIT_END_STATE;
            }
            else
            {
                throw new YamlException("Expected DOCUMENT-START or STREAM-END");
            }
        }

        /// <summary>
        /// Check if the document content is an empty scalar.
        /// </summary>
        private bool CheckEmptyDocument()
        {
            int index = 0;
            foreach (var parsingEvent in events)
            {
                if (++index == 2)
                {
                    Scalar scalar = parsingEvent as Scalar;
                    if (scalar != null)
                    {
                        return string.IsNullOrEmpty(scalar.Value);
                    }

View on GitHub (pinned to 96fad776d2)