stride3d/stride · error · SemanticErrorException

Found incompatible YAML document.

Error message

Found incompatible YAML document.

What it means

The library only supports the YAML version it was built against (Constants.MajorVersion/MinorVersion, i.e. 1.1). A %YAML directive announcing a different major/minor version makes the document incompatible and a SemanticErrorException is thrown at the directive's span.

Solutions

1. Change the directive to %YAML 1.1
2. Remove the %YAML line entirely — the parser then assumes its supported version
3. Rewrite any 1.2-specific syntax (e.g. certain merge/sexagesimal behaviors) that differs from 1.1

Example fix

// before
%YAML 1.2
---
key: value
// after
%YAML 1.1
---
key: value

foreach (var line in File.ReadLines(path))
    if (line.TrimStart().StartsWith("%YAML ") && !line.Contains("1.1"))
        throw new UnsupportedYamlVersionException(line);

try { stream.Load(reader); } catch (SemanticErrorException ex) when (ex.Message.Contains("incompatible")) { throw new YamlConfigException("Only YAML 1.1 is supported by this library", ex); }

When it happens

Trigger: A document containing "%YAML 1.2" (or any version other than 1.1) parsed by this library.

Common situations: Configs authored for YAML 1.2 parsers, tools that stamp %YAML 1.2 into their output, migrating configs between YAML libraries.

Related errors

• While scanning a %YAML directive, did not find expected…
• Incompatible %YAML directive
• Found duplicate %YAML directive.
• Found duplicate %TAG directive.
• While scanning a directive, find uknown directive name.

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

Appendix: source

Thrown at sources/core/Stride.Core.Yaml/Parser.cs:324

        private VersionDirective ProcessDirectives(TagDirectiveCollection tags)
        {
            VersionDirective version = null;

            while (true)
            {
                VersionDirective currentVersion;
                TagDirective tag;

                if ((currentVersion = GetCurrentToken() as VersionDirective) != null)
                {
                    if (version != null)
                    {
                        throw new SemanticErrorException(currentVersion.Start, currentVersion.End, "Found duplicate %YAML directive.");
                    }

                    if (currentVersion.Version.Major != Constants.MajorVersion || currentVersion.Version.Minor != Constants.MinorVersion)
                    {
                        throw new SemanticErrorException(currentVersion.Start, currentVersion.End, "Found incompatible YAML document.");
                    }

                    version = currentVersion;
                }
                else if ((tag = GetCurrentToken() as TagDirective) != null)
                {
                    if (tagDirectives.Contains(tag.Handle))
                    {
                        throw new SemanticErrorException(tag.Start, tag.End, "Found duplicate %TAG directive.");
                    }
                    tagDirectives.Add(tag);
                    if (tags != null)
                    {
                        tags.Add(tag);
                    }
                }
                else
                {

View on GitHub (pinned to 96fad776d2)