stride3d/stride · error · SyntaxErrorException

While scanning a directive, find uknown directive name.

Error message

While scanning a directive, find uknown directive name.

What it means

YAML scanner error in ScanDirective: the directive name at the top of the document is neither YAML nor TAG, and unknown directives are rejected. The input file uses an unsupported %DIRECTIVE (e.g. %RESOLVE or a typo).

Solutions

Remove or correct the unknown %directive line at the start of the YAML document
Use only %YAML and %TAG directives, with correct spelling

Example fix

// before
%INCLUDE other.yaml
key: value
// after
key: value

Defensive patterns

Strategy: validation

Validate before calling

// Reject any % directive that is not YAML or TAG
foreach (var line in yamlText.Split('\n')) { var t = line.TrimStart(); if (t.StartsWith("%") && !t.StartsWith("%YAML") && !t.StartsWith("%TAG")) throw new FormatException("Unsupported directive: " + t); }

Try / catch

catch (SyntaxErrorException ex) { throw new ConfigFormatException($"Unknown % directive near {ex.Start.Line}"); }

Prevention

Remember YAML has no %INCLUDE — split/merge files in code instead
Process template directives before YAML parsing
Only %YAML and %TAG are valid directives

When it happens

Trigger: A line starting with '%NAME ...' where NAME is not YAML or TAG, e.g. '%INCLUDE file.yaml' or a template directive left in the file.

Common situations: Mixing preprocessor/template syntax (e.g. other tooling directives) into plain YAML, or typos like '%YML 1.2'.

Related errors

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

Appendix: source

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

            // Scan the directive name.

            string name = ScanDirectiveName(start);

            // Is it a YAML directive?

            Token directive;
            switch (name)
            {
                case "YAML":
                    directive = ScanVersionDirectiveValue(start);
                    break;

                case "TAG":
                    directive = ScanTagDirectiveValue(start);
                    break;

                default:
                    throw new SyntaxErrorException(start, mark, "While scanning a directive, find uknown directive name.");
            }

            // Eat the rest of the line including any comments.

            while (analyzer.IsBlank())
            {
                Skip();
            }

            if (analyzer.Check('#'))
            {
                while (!analyzer.IsBreakOrZero())
                {
                    Skip();
                }
            }

            // Check if we are at the end of the line.

View on GitHub (pinned to 96fad776d2)