{"record":{"id":"9d18ff232506388a","repo":"antlr/antlr4","slug":"error-creating-an-instanceof-the-antlr-tool","errorCode":null,"errorMessage":"Error creating an instanceof the ANTLR tool.","messagePattern":"Error creating an instanceof the ANTLR tool\\.","errorType":"exception","errorClass":"MojoFailureException","httpStatus":null,"severity":"error","filePath":"antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java","lineNumber":282,"sourceCode":"        try {\n\t\t\tList<String> args = getCommandArguments();\n            grammarFiles = getGrammarFiles(sourceDirectory);\n            importGrammarFiles = getImportFiles(sourceDirectory);\n            argumentSets = processGrammarFiles(args, grammarFiles, dependencies, sourceDirectory);\n        } catch (Exception e) {\n            log.error(e);\n            throw new MojoExecutionException(\"Fatal error occured while evaluating the names of the grammar files to analyze\", e);\n        }\n\n\t\tlog.debug(\"Output directory base will be \" + outputDirectory.getAbsolutePath());\n\t\tlog.info(\"ANTLR 4: Processing source directory \" + sourceDirectory.getAbsolutePath());\n\t\tfor (List<String> args : argumentSets) {\n\t\t\ttry {\n\t\t\t\t// Create an instance of the ANTLR 4 build tool\n\t\t\t\ttool = new CustomTool(args.toArray(new String[0]));\n\t\t\t} catch (Exception e) {\n\t\t\t\tlog.error(\"The attempt to create the ANTLR 4 build tool failed, see exception report for details\", e);\n\t\t\t\tthrow new MojoFailureException(\"Error creating an instanceof the ANTLR tool.\", e);\n\t\t\t}\n\n            try {\n                dependencies.analyze(grammarFiles, importGrammarFiles, tool);\n            } catch (Exception e) {\n                log.error(\"Dependency analysis failed, see exception report for details\",\n                    e);\n                throw new MojoFailureException(\"Dependency analysis failed.\", e);\n            }\n\n\t\t\t// Set working directory for ANTLR to be the base source directory\n\t\t\ttool.inputDirectory = sourceDirectory;\n\n\t\t\ttool.processGrammarsOnCommandLine();\n\n\t\t\t// If any of the grammar files caused errors but did nto throw exceptions\n\t\t\t// then we should have accumulated errors in the counts\n\t\t\tif (tool.getNumErrors() > 0) {","sourceCodeStart":264,"sourceCodeEnd":300,"githubUrl":"https://github.com/antlr/antlr4/blob/7d5770395bb7b02eb56e7c62662cb1d7c08f42a3/antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java#L264-L300","documentation":"While compiling a pattern, a tag whose first character is uppercase (e.g. <ID>) is treated as a token reference; the matcher asks the parser for its token type via getTokenType and gets Token.INVALID_TYPE back, meaning no such token exists in the grammar. IllegalArgumentException names the offending tag so you can fix the pattern or grammar.","triggerScenarios":"Compiling a pattern like \"<EXPR>\" where EXPR is a parser rule, not a token; using a token name that is misspelled or was renamed in the grammar; matching against a parser generated from a different grammar version than the pattern assumes.","commonSituations":"Patterns written against an older grammar after token renames; confusion between rule names (lowercase by convention) and token names (uppercase); copy-pasting patterns between projects with different grammars.","solutions":["Check the generated parser's *Lexer.java / .tokens file for the exact token name and use it verbatim.","If the tag refers to a rule, use the lowercase rule name (<expr>) instead.","Regenerate the parser from the current grammar and update patterns in the same change.","Add unit tests that compile all patterns once at startup so mismatches surface immediately."],"exampleFix":"// before\nParseTreePattern p = m.compile(\"<EXPR>\", R.expr); // EXPR is a rule, not a token\n\n// after\nParseTreePattern p = m.compile(\"<expr>\", R.expr);","handlingStrategy":"try-catch","validationCode":"if (parser.getTokenType(tagName) == Token.INVALID_TYPE) {\n    throw new IllegalArgumentException(\"not a token in this grammar: \" + tagName);\n}","typeGuard":"boolean isKnownToken(Parser p, String tag) {\n    return Character.isUpperCase(tag.charAt(0)) && p.getTokenType(tag) != Token.INVALID_TYPE;\n}","tryCatchPattern":"try {\n    pattern = matcher.compile(patternText, ruleIndex);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Unknown token\")) {\n        logGrammarMismatch(patternText, e.getMessage());\n    }\n    throw e;\n}","preventionTips":["Cross-check pattern tag names against the generated .tokens file.","Use lowercase for rule tags, uppercase for token tags, per grammar convention.","Compile all patterns in one startup test to catch drift after grammar changes.","Regenerate parser and update patterns in the same commit."],"tags":["antlr","java","parse-tree-pattern","pattern-compile","grammar-mismatch"],"backgroundTag":null,"analyzedSha":"7d5770395bb7b02eb56e7c62662cb1d7c08f42a3","analyzedAt":"2026-08-14T14:47:56.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}