antlr/antlr4 · error · ArgumentException

ruleName cannot be null or empty.

Error message

ruleName cannot be null or empty.

What it means

RuleTagToken's constructor rejects a null or empty ruleName. RuleTagToken is the internal token the pattern matcher conjures for a rule tag like <expr>; it must carry the rule name so matching can compare it against real rule invocations. The check fires when the token is built with an empty rule name.

Source

Thrown at runtime/CSharp/src/Tree/Pattern/RuleTagToken.cs:92

        /// <param name="label">
        /// The label associated with the rule tag, or
        /// <see langword="null"/>
        /// if
        /// the rule tag is unlabeled.
        /// </param>
        /// <exception>
        /// IllegalArgumentException
        /// if
        /// <paramref name="ruleName"/>
        /// is
        /// <see langword="null"/>
        /// or empty.
        /// </exception>
        public RuleTagToken(string ruleName, int bypassTokenType, string label)
        {
            if (string.IsNullOrEmpty(ruleName))
            {
                throw new ArgumentException("ruleName cannot be null or empty.");
            }
            this.ruleName = ruleName;
            this.bypassTokenType = bypassTokenType;
            this.label = label;
        }

        /// <summary>Gets the name of the rule associated with this rule tag.</summary>
        /// <remarks>Gets the name of the rule associated with this rule tag.</remarks>
        /// <returns>The name of the parser rule associated with this rule tag.</returns>
        [NotNull]
        public string RuleName
        {
            get
            {
                return ruleName;
            }
        }

View on GitHub (pinned to 7d5770395b)

Solutions

1. Pass the non-empty rule name exactly as declared in the grammar.
2. Ensure tag chunks are never constructed with empty tags — validate pattern strings for '<>' before compiling.
3. Prefer letting ParseTreePatternMatcher create RuleTagTokens via Compile instead of constructing them directly.

Example fix

// before
var t = new RuleTagToken(ruleNameField /* maybe empty */, type, label);

// after
if (string.IsNullOrEmpty(ruleNameField)) throw new ArgumentException(nameof(ruleNameField));
var t = new RuleTagToken(ruleNameField, type, label);

if (string.IsNullOrEmpty(ruleName)) throw new ArgumentException("ruleName required", nameof(ruleName));
var t = new RuleTagToken(ruleName, bypassTokenType, label);

static bool IsValidRuleName(string s) => !string.IsNullOrEmpty(s);

When it happens

Trigger: Direct construction new RuleTagToken("", bypassTokenType, label); via the matcher when a tag chunk somehow has an empty tag (normally TagChunk already rejects empty tags, so this is a defense-in-depth guard).

Common situations: Building custom pattern tokens by hand; string manipulation producing an empty tag between delimiters like '<>' combined with a bypassed TagChunk path; porting code between runtimes where an intermediate guard is missing.

Related errors

• pattern cannot be null
• tag cannot be null or empty
• text cannot be null
• target cannot be null.
• tokenSource cannot be null

AI-assisted analysis of antlr/antlr4@7d5770395b (2026-08-14). Data as JSON: /api/errors/5818881a173195a0. Report an issue: GitHub.