What causes "Incompatible %YAML directive" in stride3d/stride?

Remove the %YAML directive from the emitted document so the emitter writes its default version

stride3d/stride · error · YamlException

Incompatible %YAML directive

Error message

Incompatible %YAML directive

What it means

The emitter only supports emitting YAML matching the version constants compiled into the library (MajorVersion/MinorVersion, i.e. YAML 1.1). A %YAML directive declaring a different version is rejected by Emitter.AnalyzeVersionDirective with this YamlException.

Solutions

Remove the %YAML directive from the emitted document so the emitter writes its default version
Change the VersionDirective to the version the library supports (check Stride.Core.Yaml Constants.MajorVersion/MinorVersion)
Pre-process input files to rewrite %YAML 1.2 to the supported version before emitting
Use a YAML 1.2-capable emitter if 1.2 output is mandatory

Example fix

// before
new DocumentStart(new VersionDirective(new Version(1, 2)), null, true);
// after
new DocumentStart(new VersionDirective(new Version(1, 1)), null, true);

Defensive patterns

Strategy: validation

Validate before calling

bool ok = versionDirective == null || (versionDirective.Version.Major == 1 && versionDirective.Version.Minor == 1);
if (!ok) throw new InvalidOperationException("Only YAML 1.1 %YAML directive is supported by this emitter");

Try / catch

try { emitter.Emit(docStart); }
catch (YamlException ex) when (ex.Message.Contains("Incompatible %YAML")) { /* drop or rewrite the VersionDirective and retry */ }

Prevention

Omit the %YAML directive unless a specific version is required
Never carry a parsed %YAML 1.2 directive over into re-emitted output
Pin toolchains to one YAML version

When it happens

Trigger: Emitting a DocumentStart event whose VersionDirective declares a %YAML 1.2 (or any major/minor other than the library's supported pair) while the emitter writes the document stream.

Common situations: Parsing YAML 1.2 documents elsewhere and re-emitting them with Stride.Core.Yaml; copy-pasting %YAML 1.2 headers from specs or other tools; upgrading a pipeline that standardized on YAML 1.2.

Related errors

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

Appendix: source

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

                else
                {
                    throw new YamlException("Duplicate %TAG directive.");
                }
            }
            else
            {
                tagDirectives.Add(value);
            }
        }

        /// <summary>
        /// Check if a %YAML directive is valid.
        /// </summary>
        private static void AnalyzeVersionDirective(VersionDirective versionDirective)
        {
            if (versionDirective.Version.Major != Constants.MajorVersion || versionDirective.Version.Minor != Constants.MinorVersion)
            {
                throw new YamlException("Incompatible %YAML directive");
            }
        }

        private void WriteIndicator(string indicator, bool needWhitespace, bool whitespace, bool indentation)
        {
            if (needWhitespace && !isWhitespace)
            {
                Write(' ');
            }

            Write(indicator);

            isWhitespace = whitespace;
            isIndentation &= indentation;
            isOpenEnded = false;
        }

        private void WriteIndent()

View on GitHub (pinned to 96fad776d2)