antlr/antlr4 · error · ArgumentException

pattern cannot be null

Error message

pattern cannot be null

What it means

ParseTreeMatch's constructor rejects a null ParseTreePattern. The match result must know which pattern produced it (Callers use Match.Pattern to inspect labels/tags), so a null pattern makes the object meaningless. Like the tree check, this fires only when code constructs ParseTreeMatch directly with a null pattern.

Source

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

        /// 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"/>
        /// .
        /// <p>For example, for pattern
        /// <c>&lt;id:ID&gt;</c>
        /// ,

View on GitHub (pinned to 7d5770395b)

Solutions

1. Obtain the pattern via parser.CompileParseTreePattern(patternText, patternRuleIndex) or the pattern variable already in scope and pass that.
2. Ensure custom matcher subclasses store and forward the ParseTreePattern they were constructed with.
3. Add a null check on the pattern before building the match result and fail with your own clearer error message.

Example fix

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

// after
var pattern = parser.CompileParseTreePattern("<ID> = <expr>", ParserRuleContext.EXPR);
var m = new ParseTreeMatch(tree, pattern, labels, mismatch);

if (pattern == null) throw new InvalidOperationException("pattern must be compiled first");
var m = new ParseTreeMatch(tree, pattern, labels, mismatch);

static bool HasPattern(ParseTreePattern p) => p != null;

When it happens

Trigger: new ParseTreeMatch(tree, null, labels, mismatchedNode); a custom matcher that forwards a pattern field which was never initialized (e.g. forgot to pass the pattern through the constructor of the subclass).

Common situations: Subclassing ParseTreePatternMatcher or ParseTreePattern and forgetting to propagate the pattern; refactoring that drops the pattern parameter; test scaffolding that stubs out pattern state.

Related errors

• tree cannot be null
• labels cannot be null
• ruleName cannot be null or empty.
• tag cannot be null or empty
• text cannot be null

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