stride3d/stride · error · SemanticErrorException

While parsing a node, find undefined tag handle.

Error message

While parsing a node, find undefined tag handle.

What it means

When a node carries a tag using a handle like '!e!suffix', the parser resolves the handle against the document's %TAG directives (plus default handles !! and !). If the handle was never declared and is not a default, ParseNode throws SemanticErrorException at the tag's span.

Solutions

1. Add the missing %TAG directive at the top of the document (e.g. %TAG !foo! tag:example.com,2000:)
2. Use the default handle instead: replace '!foo!suffix' with '!!suffix' for standard tags
3. Use a local tag '!suffix' which requires no directive

Example fix

// before
%YAML 1.1
---
key: !foo! value
// after
%YAML 1.1
%TAG !foo! tag:example.com,2000:
---
key: !foo! value

// collect declared handles first
var handles = new HashSet<string> { "!!", "!" };
foreach (var line in File.ReadLines(path))
    if (line.StartsWith("%TAG ")) handles.Add(line.Split(' ')[1]);
// then scan node tags like !foo!suffix
foreach (Match m in Regex.Matches(text, @"!(\w+)(?=" + "!" + @")"))
    if (!handles.Contains("!" + m.Groups[1].Value + "!")) throw new InvalidDataException($"Undeclared tag handle !{m.Groups[1].Value}!");

try { stream.Load(reader); } catch (SemanticErrorException ex) when (ex.Message.Contains("undefined tag handle")) { throw new YamlConfigException($"Tag handle not declared via %TAG: {ex.Message}", ex); }

When it happens

Trigger: A node tagged with a custom handle that has no matching %TAG directive, e.g. "key: !foo! bar" with no "%TAG !foo! ..." line in the document.

Common situations: Copy-pasting YAML from docs that assumed %TAG declarations elsewhere, splitting a multi-document file and losing the directives document, hand-editing tags with custom handles.

Related errors

• Expected ' ', got ' ' (at line , character ).
• Did not find expected <stream-start>.
• Did not find expected
• Found duplicate %TAG directive.
• While parsing a node, did not find expected node content.

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

Appendix: source

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

                {
                    break;
                }
            }

            string tagName = null;
            if (tag != null)
            {
                if (string.IsNullOrEmpty(tag.Handle))
                {
                    tagName = tag.Suffix;
                }
                else if (tagDirectives.Contains(tag.Handle))
                {
                    tagName = string.Concat(tagDirectives[tag.Handle].Prefix, tag.Suffix);
                }
                else
                {
                    throw new SemanticErrorException(tag.Start, tag.End, "While parsing a node, find undefined tag handle.");
                }
            }
            if (string.IsNullOrEmpty(tagName))
            {
                tagName = null;
            }

            string anchorName = anchor != null ? string.IsNullOrEmpty(anchor.Value) ? null : anchor.Value : null;

            bool isImplicit = string.IsNullOrEmpty(tagName);

            if (isIndentlessSequence && GetCurrentToken() is BlockEntry)
            {
                state = ParserState.YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE;

                return new Events.SequenceStart(
                    anchorName,
                    tagName,

View on GitHub (pinned to 96fad776d2)