antlr/antlr4 · error · IllegalArgumentException

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

Error message

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

What it means

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

Source

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

			}
		}
		return null;
	}

	public List<? extends Token> tokenize(String pattern) {
		// split pattern into chunks: sea (raw input) and islands (<ID>, <expr>)
		List<Chunk> chunks = split(pattern);

		// 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;

View on GitHub (pinned to 7d5770395b)

Solutions

1. Use a token name that exists in the target grammar's token vocabulary inside the tag.
2. Check token names via lexer.getVocabulary() or the generated XxxParser.ID constants; token tags are case-sensitive and must match the literal name.
3. If you meant a rule, prefix accordingly — rules start lowercase, tokens uppercase.

Example fix

// grammar defines: ID : [a-z]+; and rule expr
ParseTreePattern p = matcher.compile("<ID> = <expr>;", MyParser.RULE_assign);

When it happens

Trigger: A <tag> in a pattern refers to a name that is not a token type defined in the lexer grammar.

Common situations: Verify tag names against lexer token vocabulary; token tags are case-sensitive and must match defined token names.

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