stride3d/stride · error · ArgumentNullException

Tag handle must not be empty.

Error message

Tag handle must not be empty.

What it means

The TagDirective token constructor throws ArgumentNullException (with a descriptive message) when the YAML %TAG directive's handle is null or empty. A tag handle is the short prefix like '!' or '!e!'; without it the directive is meaningless so the library rejects it eagerly at token construction time.

Solutions

1. Correct the %TAG directive in the YAML source so it has a non-empty handle (e.g. `!e!`).
2. If constructing programmatically, validate `!string.IsNullOrEmpty(handle)` before `new TagDirective(...)`.
3. Remove the %TAG directive if tag shorthand is not needed and use full tag URIs instead.

Example fix

// before (YAML)
%TAG ! <>
---
foo: bar
// after (YAML)
%TAG !e! tag:example.com,2000:
---
foo: bar

if (string.IsNullOrEmpty(handle))
    throw new ArgumentException("%TAG directive requires a non-empty handle.");
var token = new TagDirective(handle, prefix, start, end);

static bool IsValidTagHandle(string h) => !string.IsNullOrEmpty(h);

try { return new TagDirective(handle, prefix, start, end); }
catch (ArgumentNullException ex) { throw new YamlSyntaxException($"Malformed %TAG directive: {ex.Message}", start); }

When it happens

Trigger: Parsing a YAML document containing a %TAG directive with an empty handle (e.g. `%TAG ! <>` with an empty handle field), or constructing a TagDirective directly with null/empty handle.

Common situations: Hand-edited YAML config files with malformed %TAG directives; template-generated YAML where a tag placeholder was left empty; programmatic YAML emission bugs.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Tag prefix must not be empty.
• Attributes can not be null
• factory
• Found duplicate %TAG directive.
• Found duplicate %YAML directive.

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

Appendix: source

Thrown at sources/core/Stride.Core.Yaml/Tokens/TagDirective.cs:96

            : this(handle, prefix, Mark.Empty, Mark.Empty)
        {
        }

        private static readonly Regex tagHandleValidator = new Regex(@"^!([0-9A-Za-z_\-]*!)?$");

        /// <summary>
        /// Initializes a new instance of the <see cref="TagDirective"/> class.
        /// </summary>
        /// <param name="handle">The handle.</param>
        /// <param name="prefix">The prefix.</param>
        /// <param name="start">The start position of the token.</param>
        /// <param name="end">The end position of the token.</param>
        public TagDirective(string handle, string prefix, Mark start, Mark end)
            : base(start, end)
        {
            if (string.IsNullOrEmpty(handle))
            {
                throw new ArgumentNullException("handle", "Tag handle must not be empty.");
            }

            if (!tagHandleValidator.IsMatch(handle))
            {
                throw new ArgumentException("Tag handle must start and end with '!' and contain alphanumerical characters only.", "handle");
            }

            this.handle = handle;

            if (string.IsNullOrEmpty(prefix))
            {
                throw new ArgumentNullException("prefix", "Tag prefix must not be empty.");
            }

            this.prefix = prefix;
        }

        /// <summary>

View on GitHub (pinned to 96fad776d2)