antlr/antlr4 · warning · UnsupportedOperationException

This ATN simulator does not support clearing the DFA.

Error message

This ATN simulator does not support clearing the DFA.

What it means

ATNSimulator.clearDFA() is a base-class stub: only the concrete simulators (ParserATNSimulator and LexerATNSimulator) override it to drop their DFA cache. Calling it on the abstract base type (or on a subclass such as a profiling simulator that does not override it) throws UnsupportedOperationException. The DFA cache only affects speed, never correctness, so clearing is an optional optimization.

Source

Thrown at runtime/Java/src/org/antlr/v4/runtime/atn/ATNSimulator.java:70

		this.atn = atn;
		this.sharedContextCache = sharedContextCache;
	}

	public abstract void reset();

	/**
	 * Clear the DFA cache used by the current instance. Since the DFA cache may
	 * be shared by multiple ATN simulators, this method may affect the
	 * performance (but not accuracy) of other parsers which are being used
	 * concurrently.
	 *
	 * @throws UnsupportedOperationException if the current instance does not
	 * support clearing the DFA.
	 *
	 * @since 4.3
	 */
	public void clearDFA() {
		throw new UnsupportedOperationException("This ATN simulator does not support clearing the DFA.");
	}

	public PredictionContextCache getSharedContextCache() {
		return sharedContextCache;
	}

	public PredictionContext getCachedContext(PredictionContext context) {
		if ( sharedContextCache==null ) return context;

		synchronized (sharedContextCache) {
			IdentityHashMap<PredictionContext, PredictionContext> visited =
				new IdentityHashMap<PredictionContext, PredictionContext>();
			return PredictionContext.getCachedContext(context,
													  sharedContextCache,
													  visited);
		}
	}
}

View on GitHub (pinned to 7d5770395b)

Solutions

Call clearDFA() on the concrete type: cast to ParserATNSimulator or LexerATNSimulator first (instanceof check)
If you own the subclass, override clearDFA() and clear whatever DFA state it holds (or delegate to the wrapped simulator)
Otherwise create a fresh parser/lexer instance; a new simulator starts with an empty DFA

Example fix

// before
ATNSimulator sim = parser.getInterpreter();
sim.clearDFA(); // throws if not overridden
// after
ATNSimulator sim = parser.getInterpreter();
if (sim instanceof ParserATNSimulator) {
    ((ParserATNSimulator) sim).clearDFA();
}

Defensive patterns

Strategy: type-guard

Validate before calling

if (sim instanceof ParserATNSimulator) ((ParserATNSimulator) sim).clearDFA();
else if (sim instanceof LexerATNSimulator) ((LexerATNSimulator) sim).clearDFA();
else { /* create fresh parser/lexer instead */ }

Type guard

static boolean canClearDfa(ATNSimulator sim) {
    return sim instanceof ParserATNSimulator || sim instanceof LexerATNSimulator;
}

Prevention

Hold simulators by their concrete type when you need cache management
Prefer constructing a new parser/lexer over clearing a shared DFA
Wrap custom ATNSimulator subclasses so they delegate clearDFA

When it happens

Trigger: Invoking clearDFA() on a variable statically typed as ATNSimulator, or on a custom ATNSimulator subclass (e.g. a profiling or wrapper simulator) that inherits the base implementation. Typical call sites are long-running services that reset the cache to reclaim memory or after loading new grammars.

Common situations: Memory-leak workarounds in long-lived parser services. Test harnesses that want a cold DFA between runs. Upgrading to ANTLR 4.3+ where clearDFA was introduced and calling it through the base type.

Related errors

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