What causes "While parsing a tag directive, did not find expected '!'." in stride3d/stride?

Make the %TAG handle exactly '!', e.g. '%TAG ! tag:example.com,2000:' or '%TAG !e! tag:example.com,2000:' (handle '!e!' is allowed as it is the named-handle form; the failing case is a malformed handle like 'foo').

stride3d/stride · error · SyntaxErrorException

While parsing a tag directive, did not find expected '!'.

Error message

While parsing a tag directive, did not find expected '!'.

What it means

In Scanner.ScanTagHandle, when scanning a %TAG directive the handle must be exactly one character ('!'), because directive tag handles are only the primary handle '!'. If a directive yields a longer handle not ending in '!' (or otherwise length != 1), the scanner throws SyntaxErrorException.

Solutions

Make the %TAG handle exactly '!', e.g. '%TAG ! tag:example.com,2000:' or '%TAG !e! tag:example.com,2000:' (handle '!e!' is allowed as it is the named-handle form; the failing case is a malformed handle like 'foo').
If you meant a document-level tag, move it out of the directive line and use '!local!suffix' syntax in the document body.
Run the file through a YAML validator before deserializing.
Catch SyntaxErrorException and report the mark/line of the directive.

Example fix

// before (input.yaml)
%TAG e tag:example.com,2000:

// after (input.yaml)
%TAG !e! tag:example.com,2000:

Defensive patterns

Strategy: validation

Validate before calling

// C#
foreach (var line in yamlText.Split('\n').Where(l => l.TrimStart().StartsWith("%TAG")))
{
    var handle = line.Trim().Split(' ')[1];
    if (handle != "!" && !(handle.StartsWith("!") && handle.EndsWith("!")))
        throw new FormatException($"Bad %TAG handle '{handle}'; use '!' or '!name!'.");
}

Try / catch

try { deserializer.Deserialize(reader, targetType); }
catch (SyntaxErrorException ex) { throw new YamlConfigException($"Invalid %TAG directive handle at line {ex.Start.Line}", ex); }

Prevention

Use the canonical forms: '!' (primary) or '!name!' (named) in %TAG directives.
Never put bare suffixes or URI fragments in the handle slot.
Copy %TAG syntax from the YAML 1.1/1.2 spec examples when hand-writing.

When it happens

Trigger: A %TAG directive whose handle portion is not exactly '!', e.g. '%TAG !foo! ' misspelled without trailing '!' is legal, but '%TAG foo bar' or '%TAG !!' forms that leave a handle of length != 1 in directive mode.

Common situations: Hand-written %TAG directives with typos; forgetting that directive handles are only '!' (named handles like '!e!' belong in document tags, not %TAG); editing generated YAML by hand.

Related errors

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

Appendix: source

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

                tagHandle.Append(ReadCurrentCharacter());
            }

            // Check if the trailing character is '!' and copy it.

            if (analyzer.Check('!'))
            {
                tagHandle.Append(ReadCurrentCharacter());
            }
            else
            {
                // It's either the '!' tag or not really a tag handle.  If it's a %TAG
                // directive, it's an error.  If it's a tag token, it must be a part of
                // URI.


                if (isDirective && (tagHandle.Length != 1 || tagHandle[0] != '!'))
                {
                    throw new SyntaxErrorException(start, mark, "While parsing a tag directive, did not find expected '!'.");
                }
            }

            return tagHandle.ToString();
        }

        /// <summary>
        /// Scan the version number of VERSION-DIRECTIVE.
        ///
        /// Scope:
        ///      %YAML   1.1     # a comment \n
        ///              ^
        ///      %YAML   1.1     # a comment \n
        ///                ^
        /// </summary>
        private int ScanVersionDirectiveNumber(Mark start)
        {
            int value = 0;

View on GitHub (pinned to 96fad776d2)