gradle/gradle · error · IllegalStateException

Unable to locate Antlr class [%s]

Error message

Unable to locate Antlr class [%s]

What it means

GrammarDelegate's static initializer eagerly loads 'antlr.preprocessor.Grammar' and 'antlr.preprocessor.Option' via Class.forName with GrammarDelegate's classloader. If either class is missing, the initializer throws IllegalStateException("Unable to locate Antlr class [...]") - so this surfaces as an ExceptionInInitializerError wrapping this exception at first use. It simply means ANTLR 2 classes are not on the executing classpath.

Source

Thrown at platforms/jvm/antlr/src/main/java/org/gradle/api/plugins/antlr/internal/antlr2/GrammarDelegate.java:145

        return vocabName;
    }

    private static final Class<?> ANTLR_GRAMMAR_CLASS;
    private static final Class<?> ANTLR_OPTION_CLASS;

    static {
        ANTLR_GRAMMAR_CLASS = loadAntlrClass("antlr.preprocessor.Grammar");
        ANTLR_OPTION_CLASS = loadAntlrClass("antlr.preprocessor.Option");
    }

    public static final Class<?>[] NO_ARG_SIGNATURE = new Class<?>[0];
    public static final Object[] NO_ARGS = new Object[0];

    private static Class<?> loadAntlrClass(String className) {
        try {
            return Class.forName(className, true, GrammarDelegate.class.getClassLoader());
        } catch (ClassNotFoundException e) {
            throw new IllegalStateException("Unable to locate Antlr class [" + className + "]", e);
        }
    }
}

View on GitHub (pinned to 534f27719b)

Solutions

1. Add the antlr2 tool: dependencies { antlr 'antlr:antlr:2.7.7' }
2. Or remove/exclude the stale antlr2 grammar files from the AntlrTask source if the project migrated to ANTLR 3/4
3. Verify with './gradlew dependencies --configuration antlr' that the antlr2 jar actually resolves

Example fix

// before: only antlr4, but a legacy .g (antlr2) grammar is still in source
dependencies { antlr 'org.antlr:antlr4:4.13.2' }

// after: add the antlr2 tool for the legacy grammar (or delete the grammar)
dependencies {
    antlr 'antlr:antlr:2.7.7'
}

// guard legacy antlr2 processing
tasks.matching { it.name ==~ /generate.*GrammarSource/ }.configureEach {
    doFirst {
        def legacyG2 = source.files.findAll { it.name.endsWith('.g') }
        if (!legacyG2.isEmpty()) {
            assert configurations.antlr.dependencies.any { it.group == 'antlr' } :
                "legacy antlr2 grammars (${legacyG2*.name}) need antlr:antlr:2.7.7"
        }
    }
}

When it happens

Trigger: An antlr2 grammar (.g with preprocessor options) is processed but the antlr configuration contains no antlr2 artifact (or contains antlr3/4 which do not ship antlr.preprocessor.*).

Common situations: Only org.antlr:antlr4 declared while the source set still contains legacy antlr2 grammars; a migration from antlr2 to antlr4 that left stale .g files behind.

Related errors

• Cannot configure services using %s.%s() as required service
• Cannot create service of %s using %s as required service of
• Cannot create service of %s using %s as required service of
• Failed to load ANTLR
• Cannot process antlr sources

AI-assisted analysis of gradle/gradle@534f27719b (2026-08-22). Data as JSON: /api/errors/4421e7cbe1b3ad52. Report an issue: GitHub.