stride3d/stride · error · SyntaxErrorException

While scanning a directive, could not find expected…

Error message

While scanning a directive, could not find expected directive name.

What it means

Thrown by the YAML Scanner when a '%' starts a directive line ('%YAML', '%TAG', etc.) but no directive name characters follow before whitespace, line break, or end of input. A directive line must carry a name immediately after '%'.

Solutions

Remove the stray '%' line if it was not intended as a YAML directive.
Complete the directive, e.g. '%YAML 1.1' followed by '---'.
If '%' must appear as content, quote it ('%name%') or move it after the '---' document start.
Fix the templating pipeline so placeholders are substituted before the YAML is parsed.

Example fix

// before
%name%
key: value
// after
---
key: "%name%"

Defensive patterns

Strategy: try-catch

Validate before calling

// Detect bare directive lines with empty name
bool HasBareDirective(string yaml) => yaml.Split('\n').Any(l => l.TrimEnd().TrimEnd(' ', '\t') == "%");

Try / catch

try
{
    var obj = Deserializer.FromFile(path);
}
catch (SyntaxErrorException ex)
{
    Log.Error(ex, "Malformed directive at line {Line}", ex.Start.Line);
    throw new YamlConfigException("Invalid YAML directive", ex);
}

Prevention

Ensure template placeholders (like %name%) are fully substituted before parsing
Only emit real YAML directives (%YAML, %TAG) and always with a name and arguments
Escape stray '%' characters by quoting the line as content

When it happens

Trigger: Parsing a YAML stream containing a bare '%' at the start of a line (e.g. '% ' or a lone '%' line), which the scanner reads as the start of a directive with an empty name.

Common situations: Template placeholders like '%name%' left unexpanded in YAML files; snippets pasted from LaTeX/protobuf syntax that use '%' comments; files generated by broken templating engines.

Related errors

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/ddea7f5be752bb0f. Report an issue: GitHub.

Appendix: source

Thrown at sources/core/Stride.Core.Yaml/Scanner.cs:2012

        ///      %TAG    !yaml!  tag:yaml.org,2002:  \n
        ///       ^^^
        /// </summary>
        private string ScanDirectiveName(Mark start)
        {
            StringBuilder name = new StringBuilder();

            // Consume the directive name.

            while (analyzer.IsAlpha())
            {
                name.Append(ReadCurrentCharacter());
            }

            // Check if the name is empty.

            if (name.Length == 0)
            {
                throw new SyntaxErrorException(start, mark, "While scanning a directive, could not find expected directive name.");
            }

            // Check for an blank character after the name.

            if (!analyzer.IsBlankOrBreakOrZero())
            {
                throw new SyntaxErrorException(start, mark, "While scanning a directive, find unexpected non-alphabetical character.");
            }

            return name.ToString();
        }

        private void SkipWhitespaces()
        {
            // Eat whitespaces.

            while (analyzer.IsBlank())
            {

View on GitHub (pinned to 96fad776d2)