stride3d/stride · error · SyntaxErrorException

While scanning a directive, find unexpected…

Error message

While scanning a directive, find unexpected non-alphabetical character.

What it means

Thrown by the YAML Scanner when a directive name contains a character outside the allowed alphanumeric set, or a non-blank character immediately follows the directive name. Directive names (YAML, TAG) may contain only alphanumerics and must be followed by whitespace or a line break.

Solutions

Correct the directive spelling and syntax, e.g. '%YAML 1.1' with a space before the version.
Remove unsupported directives — only %YAML and %TAG are defined.
If the line is not meant to be a directive, remove the leading '%' or quote the line as content.
Escape or strip '%' lines during preprocessing if input comes from a system that uses '%' for other syntax.

Example fix

// before
%YAML-1.1
---
// after
%YAML 1.1
---

Defensive patterns

Strategy: validation

Validate before calling

bool IsValidDirectiveLine(string line) =>
    line.StartsWith("%") &&
    System.Text.RegularExpressions.Regex.IsMatch(line, "^%[A-Za-z0-9]+[ \\t\\r\\n]");

Try / catch

try
{
    var obj = Deserializer.FromText(yaml);
}
catch (SyntaxErrorException ex)
{
    Log.Error(ex, "Non-alphabetical character in directive at line {Line}", ex.Start.Line);
    throw;
}

Prevention

Only use the standard directives '%YAML 1.1' and '%TAG handle prefix'
Never attach punctuation ('-', ':', '!') directly to a directive name
Strip or quote '%' lines coming from foreign syntaxes (LaTeX comments, Makefiles)

When it happens

Trigger: Parsing YAML with a malformed directive such as '%YAML-1.1' (hyphen attached to the name) or '%FOO!' where a punctuation character directly follows the name without whitespace.

Common situations: Typos like '%YAML1.1' or '%yaml:1.2'; custom directives invented by users that YAML does not allow; copy-paste corruption introducing punctuation into directive lines.

Related errors

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

Appendix: source

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

            // 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())
            {
                Skip();
            }
        }

        /// <summary>
        /// Scan the value of VERSION-DIRECTIVE.
        ///

View on GitHub (pinned to 96fad776d2)