antlr/antlr4 · error · ArgumentException

tree cannot be null

Error message

tree cannot be null

What it means

ParseTreeMatch's constructor rejects a null tree argument. ParseTreeMatch is the result object returned by ParseTreePattern.Match(); it must always wrap a real parse tree node. In normal use the library itself supplies a non-null tree, so hitting this means you are constructing ParseTreeMatch directly (e.g. in a custom matcher subclass) and passed null.

Source

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

        /// <exception>
        /// IllegalArgumentException
        /// if
        /// <paramref name="pattern"/>
        /// is
        /// <see langword="null"/>
        /// </exception>
        /// <exception>
        /// 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"/>

View on GitHub (pinned to 7d5770395b)

Solutions

1. Pass the IParseTree instance you received in MatchImpl/tree argument — check it for null before constructing the match result.
2. If tree can legitimately be absent, return null (as MatchImpl does for a successful full match) instead of constructing a ParseTreeMatch with a null tree.
3. Use the public API tree.Pattern(pattern).Match(tree) rather than constructing ParseTreeMatch by hand.

Example fix

// before
var m = new ParseTreeMatch(maybeTree, pattern, labels, mismatch);

// after
if (maybeTree == null) return null; // or handle absent-match case
var m = new ParseTreeMatch(maybeTree, pattern, labels, mismatch);

IParseTree maybeTree = GetTree();
if (maybeTree == null) throw new InvalidOperationException("no tree to match");
var m = new ParseTreeMatch(maybeTree, pattern, labels, mismatch);

static bool HasTree(IParseTree t) => t != null;

When it happens

Trigger: Directly invoking new ParseTreeMatch(null, pattern, labels, mismatchedNode); subclassing ParseTreePatternMatcher and building the result object from a nullable tree variable without a null check.

Common situations: Custom pattern-matching extensions that store the matched tree in a variable defaulting to null; porting Java code where an @NotNull annotation was only advisory; test helpers that fabricate ParseTreeMatch instances.

Related errors

• pattern cannot be null
• labels 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/bf81091664a977e0. Report an issue: GitHub.