antlr/antlr4 · error · MojoFailureException

Error creating an instanceof the ANTLR tool.

Error message

Error creating an instanceof the ANTLR tool.

What it means

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.

Source

Thrown at antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java:282

        try {
			List<String> args = getCommandArguments();
            grammarFiles = getGrammarFiles(sourceDirectory);
            importGrammarFiles = getImportFiles(sourceDirectory);
            argumentSets = processGrammarFiles(args, grammarFiles, dependencies, sourceDirectory);
        } catch (Exception e) {
            log.error(e);
            throw new MojoExecutionException("Fatal error occured while evaluating the names of the grammar files to analyze", e);
        }

		log.debug("Output directory base will be " + outputDirectory.getAbsolutePath());
		log.info("ANTLR 4: Processing source directory " + sourceDirectory.getAbsolutePath());
		for (List<String> args : argumentSets) {
			try {
				// Create an instance of the ANTLR 4 build tool
				tool = new CustomTool(args.toArray(new String[0]));
			} catch (Exception e) {
				log.error("The attempt to create the ANTLR 4 build tool failed, see exception report for details", e);
				throw new MojoFailureException("Error creating an instanceof the ANTLR tool.", e);
			}

            try {
                dependencies.analyze(grammarFiles, importGrammarFiles, tool);
            } catch (Exception e) {
                log.error("Dependency analysis failed, see exception report for details",
                    e);
                throw new MojoFailureException("Dependency analysis failed.", e);
            }

			// Set working directory for ANTLR to be the base source directory
			tool.inputDirectory = sourceDirectory;

			tool.processGrammarsOnCommandLine();

			// If any of the grammar files caused errors but did nto throw exceptions
			// then we should have accumulated errors in the counts
			if (tool.getNumErrors() > 0) {

View on GitHub (pinned to 7d5770395b)

Solutions

1. Check the generated parser's *Lexer.java / .tokens file for the exact token name and use it verbatim.
2. If the tag refers to a rule, use the lowercase rule name (<expr>) instead.
3. Regenerate the parser from the current grammar and update patterns in the same change.
4. Add unit tests that compile all patterns once at startup so mismatches surface immediately.

Example fix

// before
ParseTreePattern p = m.compile("<EXPR>", R.expr); // EXPR is a rule, not a token

// after
ParseTreePattern p = m.compile("<expr>", R.expr);

if (parser.getTokenType(tagName) == Token.INVALID_TYPE) {
    throw new IllegalArgumentException("not a token in this grammar: " + tagName);
}

boolean isKnownToken(Parser p, String tag) {
    return Character.isUpperCase(tag.charAt(0)) && p.getTokenType(tag) != Token.INVALID_TYPE;
}

try {
    pattern = matcher.compile(patternText, ruleIndex);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unknown token")) {
        logGrammarMismatch(patternText, e.getMessage());
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Dependency analysis failed.
• ANTLR 4 caught {} build errors.
• index cannot be negative
• missing interface implementation
• Fatal error occured while evaluating the names of the gramma

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