antlr/antlr4 · error · ArgumentException

labels cannot be null

Error message

labels cannot be null

What it means

ParseTreeMatch's constructor rejects a null labels MultiMap. The labels map (label/tag name -> matched subtrees) is the primary payload of a match result; GetAll(label), Get(label) and tree.All() downstream would all NPE if it were null. Only direct construction with a null labels map triggers this.

Source

Thrown at runtime/CSharp/src/Tree/Pattern/ParseTreeMatch.cs:99

        /// IllegalArgumentException
        /// if
        /// <paramref name="labels"/>
        /// is
        /// <see langword="null"/>
        /// </exception>
        public ParseTreeMatch(IParseTree tree, ParseTreePattern pattern, MultiMap<string, IParseTree> labels, IParseTree mismatchedNode)
        {
            if (tree == null)
            {
                throw new ArgumentException("tree cannot be null");
            }
            if (pattern == null)
            {
                throw new ArgumentException("pattern cannot be null");
            }
            if (labels == null)
            {
                throw new ArgumentException("labels cannot be null");
            }
            this.tree = tree;
            this.pattern = pattern;
            this.labels = labels;
            this.mismatchedNode = mismatchedNode;
        }

        /// <summary>
        /// Get the last node associated with a specific
        /// <paramref name="label"/>
        /// .
        /// <p>For example, for pattern
        /// <c>&lt;id:ID&gt;</c>
        /// ,
        /// <c>get("id")</c>
        /// returns the
        /// node matched for that
        /// <c>ID</c>

View on GitHub (pinned to 7d5770395b)

Solutions

1. Forward the labels MultiMap that MatchImpl receives: new ParseTreeMatch(tree, patternTree-matched labels map, mismatchedNode).
2. If constructing manually, pass new MultiMap<string, IParseTree>() instead of null when no labels are needed.
3. Use the standard entry point tree.Match(pattern) which always supplies a fresh labels map.

Example fix

// before
var m = new ParseTreeMatch(tree, pattern, null, mismatch);

// after
var labels = new MultiMap<string, IParseTree>();
var m = new ParseTreeMatch(tree, pattern, labels, mismatch);

var labels = existingLabels ?? new MultiMap<string, IParseTree>();
var m = new ParseTreeMatch(tree, pattern, labels, mismatch);

static bool HasLabels(MultiMap<string, IParseTree> l) => l != null;

When it happens

Trigger: new ParseTreeMatch(tree, pattern, null, mismatch); a custom MatchImpl override that forgets to forward the labels MultiMap parameter it was given.

Common situations: Overriding ParseTreePatternMatcher.MatchImpl and dropping the labels argument; building synthetic match results in unit tests; refactors that replaced the labels parameter with a local that is never assigned.

Related errors

• tree cannot be null
• pattern cannot be null
• target cannot be null.
• tokenSource cannot be null
• nextToken requires a non-null input stream.

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