stride3d/stride · error · ArgumentException

Tag handle must start and end with '!' and contain…

Error message

Tag handle must start and end with '!' and contain alphanumerical characters only.

What it means

TagDirective's constructor throws ArgumentException when the tag handle fails the tagHandleValidator regex: it must start and end with '!' and contain only alphanumerical characters between (e.g. '!e!'). This enforces the YAML tag-shorthand grammar before the token is accepted.

Solutions

1. Rewrite the handle to match !name! (leading and trailing '!', alphanumeric middle), e.g. `!e!`.
2. Validate with the same regex before constructing/parsing: `^![0-9A-Za-z]*!$`.
3. Use the primary handle `!` alone if no named shorthand is required.

Example fix

// before (YAML)
%TAG e! tag:example.com,2000:
// after (YAML)
%TAG !e! tag:example.com,2000:

var tagHandleRegex = new System.Text.RegularExpressions.Regex("^![0-9A-Za-z]*!$");
if (string.IsNullOrEmpty(handle) || !tagHandleRegex.IsMatch(handle))
    throw new ArgumentException($"Invalid tag handle '{handle}': must be !name! with alphanumerics only.");

static bool IsValidTagHandle(string h) => h != null && System.Text.RegularExpressions.Regex.IsMatch(h, "^![0-9A-Za-z]*!$");

try { return new TagDirective(handle, prefix, start, end); }
catch (ArgumentException ex) { throw new YamlSyntaxException($"Invalid tag shorthand in %TAG directive: {ex.Message}", start); }

When it happens

Trigger: Parsing a %TAG directive whose handle is malformed, e.g. `%TAG e! tag:...` (missing leading '!') or `%TAG !e tag:...` (missing trailing '!'), or constructing TagDirective directly with such a handle.

Common situations: Typo'd YAML tag directives in config files; YAML authored by hand or generated by tools that don't validate the tag-shorthand syntax.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Expecting length >= 2 and at least a special character '.'…
• Found duplicate %TAG directive.
• Found duplicate %YAML directive.
• Found incompatible YAML document.
• Tag handle must not be empty.

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

Appendix: source

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

        /// <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>
        /// Determines whether the specified System.Object is equal to the current System.Object.
        /// </summary>
        /// <param name="obj">The System.Object to compare with the current System.Object.</param>
        /// <returns>
        /// true if the specified System.Object is equal to the current System.Object; otherwise, false.

View on GitHub (pinned to 96fad776d2)