antlr/antlr4 · error · IllegalArgumentException

Unknown rule "+tagChunk.getTag()+" in pattern: "+pattern

Error message

Unknown rule "+tagChunk.getTag()+" in pattern: "+pattern

What it means

Error "Unknown rule "+tagChunk.getTag()+" in pattern: "+pattern" thrown in antlr/antlr4.

Source

Thrown at runtime/Java/src/org/antlr/v4/runtime/tree/pattern/ParseTreePatternMatcher.java:386

		// create token stream from text and tags
		List<Token> tokens = new ArrayList<Token>();
		for (Chunk chunk : chunks) {
			if ( chunk instanceof TagChunk ) {
				TagChunk tagChunk = (TagChunk)chunk;
				// add special rule token or conjure up new token from name
				if ( Character.isUpperCase(tagChunk.getTag().charAt(0)) ) {
					Integer ttype = parser.getTokenType(tagChunk.getTag());
					if ( ttype==Token.INVALID_TYPE ) {
						throw new IllegalArgumentException("Unknown token "+tagChunk.getTag()+" in pattern: "+pattern);
					}
					TokenTagToken t = new TokenTagToken(tagChunk.getTag(), ttype, tagChunk.getLabel());
					tokens.add(t);
				}
				else if ( Character.isLowerCase(tagChunk.getTag().charAt(0)) ) {
					int ruleIndex = parser.getRuleIndex(tagChunk.getTag());
					if ( ruleIndex==-1 ) {
						throw new IllegalArgumentException("Unknown rule "+tagChunk.getTag()+" in pattern: "+pattern);
					}
					int ruleImaginaryTokenType = parser.getATNWithBypassAlts().ruleToTokenType[ruleIndex];
					tokens.add(new RuleTagToken(tagChunk.getTag(), ruleImaginaryTokenType, tagChunk.getLabel()));
				}
				else {
					throw new IllegalArgumentException("invalid tag: "+tagChunk.getTag()+" in pattern: "+pattern);
				}
			}
			else {
				TextChunk textChunk = (TextChunk)chunk;
				ANTLRInputStream in = new ANTLRInputStream(textChunk.getText());
				lexer.setInputStream(in);
				Token t = lexer.nextToken();
				while ( t.getType()!=Token.EOF ) {
					tokens.add(t);
					t = lexer.nextToken();
				}
			}

View on GitHub (pinned to 7d5770395b)

Solutions

1. Use a rule name that exists in the target grammar inside the tag.
2. Rule tags must match the parser rule name exactly (lowercase by convention), e.g. <expr>, and the rule must exist in the grammar the matcher was built for.

Example fix

ParseTreePattern p = matcher.compile("foo(<arg>)", MyParser.RULE_call);

When it happens

Trigger: A <tag> in a pattern refers to a rule name not defined in the parser grammar.

Common situations: Check the tag against the parser's rule names; rule tags must be valid rule references or label:rule forms.

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