antlr/antlr4 · error · NullPointerException

listener

Error message

listener

What it means

Parser.addParseListener() throws NullPointerException("listener") when passed null, because every parse listener in the list receives enterRule/exitRule/visitTerminal callbacks and a null entry would break iteration during the parse. The check is documented in the Javadoc. Note this validates the argument, not the parser state — the listener list itself is created lazily on first add.

Source

Thrown at runtime/Java/src/org/antlr/v4/runtime/Parser.java:350

	 * <em>deterministic</em>, i.e. for identical input the calls to listener
	 * methods will be the same.</p>
	 *
	 * <ul>
	 * <li>Alterations to the grammar used to generate code may change the
	 * behavior of the listener calls.</li>
	 * <li>Alterations to the command line options passed to ANTLR 4 when
	 * generating the parser may change the behavior of the listener calls.</li>
	 * <li>Changing the version of the ANTLR Tool used to generate the parser
	 * may change the behavior of the listener calls.</li>
	 * </ul>
	 *
	 * @param listener the listener to add
	 *
	 * @throws NullPointerException if {@code} listener is {@code null}
	 */
	public void addParseListener(ParseTreeListener listener) {
		if (listener == null) {
			throw new NullPointerException("listener");
		}

		if (_parseListeners == null) {
			_parseListeners = new ArrayList<ParseTreeListener>();
		}

		this._parseListeners.add(listener);
	}

	/**
	 * Remove {@code listener} from the list of parse listeners.
	 *
	 * <p>If {@code listener} is {@code null} or has not been added as a parse
	 * listener, this method does nothing.</p>
	 *
	 * @see #addParseListener
	 *
	 * @param listener the listener to remove

View on GitHub (pinned to 7d5770395b)

Solutions

1. Guard the registration: if (listener != null) parser.addParseListener(listener)
2. Fix the listener construction so it never returns null (throw early at creation instead)
3. When listener registration is conditional, use Optional or an explicit if-block rather than a null placeholder

Example fix

// before
parser.addParseListener(config.isVerbose() ? verboseListener : null); // NPE when not verbose

// after
if (config.isVerbose()) parser.addParseListener(verboseListener);

if (listener != null) {
  parser.addParseListener(listener);
}

When it happens

Trigger: parser.addParseListener(null), typically because a listener variable was never constructed or a factory/DI lookup returned null; conditional listener setup where the condition left the variable null.

Common situations: Optional instrumentation added only when a flag is set but added unconditionally; listener classes with constructors that can return null from a registry; test scaffolding registering mock listeners.

Related errors

• tokenSource cannot be null
• tokens cannot be null
• The current parser does not support an ATN with bypass alter
• delegates
• The current recognizer does not provide a list of rule names

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