antlr/antlr4 · error · NullPointerException

target cannot be null.

Error message

target cannot be null.

What it means

Every Transition subclass validates in its constructor that the target ATNState is non-null and throws NullPointerException('target cannot be null.'). A transition without a target would make the ATN graph untraversable, so construction fails fast. This is almost always a programming error in code that builds ATNs by hand.

Source

Thrown at runtime/Java/src/org/antlr/v4/runtime/atn/Transition.java:78

			put(EpsilonTransition.class, EPSILON);
			put(RangeTransition.class, RANGE);
			put(RuleTransition.class, RULE);
			put(PredicateTransition.class, PREDICATE);
			put(AtomTransition.class, ATOM);
			put(ActionTransition.class, ACTION);
			put(SetTransition.class, SET);
			put(NotSetTransition.class, NOT_SET);
			put(WildcardTransition.class, WILDCARD);
			put(PrecedencePredicateTransition.class, PRECEDENCE);
		}});

	/** The target of this transition. */

	public ATNState target;

	protected Transition(ATNState target) {
		if (target == null) {
			throw new NullPointerException("target cannot be null.");
		}

		this.target = target;
	}

	public abstract int getSerializationType();

	/**
	 * Determines if the transition is an "epsilon" transition.
	 *
	 * <p>The default implementation returns {@code false}.</p>
	 *
	 * @return {@code true} if traversing this transition in the ATN does not
	 * consume an input symbol; otherwise, {@code false} if traversing this
	 * transition consumes (matches) an input symbol.
	 */
	public boolean isEpsilon() {
		return false;

View on GitHub (pinned to 7d5770395b)

Solutions

1. Fix the caller to create the target state first (atn.newState(...) / newStateOfType) and add it via atn.addState before building transitions into it
2. Add null checks / Optional at the boundary that produces the state so failures surface at the real source
3. If writing tests, use ATN test fixtures from ANTLR's own test suite rather than null stubs

Example fix

// before
ATNState target = null; // forgot to create
atn.addEdge(src, new EpsilonTransition(target)); // NPE
// after
ATNState target = atn.newState(); // e.g. BasicState
atn.addState(target);
atn.addEdge(src, new EpsilonTransition(target));

static ATNState requireState(ATNState s) {
    if (s == null) throw new IllegalStateException("target state not created yet");
    return s;
}
// then: atn.addEdge(src, new EpsilonTransition(requireState(target)));

When it happens

Trigger: new AtomTransition(null, label), new RuleTransition(ruleStart, ruleIndex, 0, null), new SetTransition(null, set), etc. Also any helper that passes a followState or target variable that was never initialized. Standard ANTLR tool/runtime code paths never pass null.

Common situations: Unit tests that stub ATN pieces. Custom ATN generators or grammar-transform tools. Refactorings where a state-creation function changed to return null on failure and callers still pass it straight into a transition constructor.

Related errors

• The specified transition type is not valid.
• Invalid state number.
• This set is readonly
• This method is not implemented for readonly sets.
• The object is read only.

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