antlr/antlr4 · error · UnsupportedOperationException

Unrecognized ATN transition type.

Error message

Unrecognized ATN transition type.

What it means

ParserInterpreter's transition-dispatch switch only handles EPSILON, RANGE, RULE, PREDICATE, ATOM, ACTION, PRECEDENCE transition types; any other label hits default and throws UnsupportedOperationException("Unrecognized ATN transition type."). Because ATN transitions gain new types only when the ANTLR tool's serialized format changes, this exception in practice means the runtime interpreter is older than (or incompatible with) the tool that serialized the ATN it is walking.

Source

Thrown at runtime/Java/src/org/antlr/v4/runtime/ParserInterpreter.java:294

				if (!sempred(_ctx, predicateTransition.ruleIndex, predicateTransition.predIndex)) {
					throw new FailedPredicateException(this);
				}

				break;

			case Transition.ACTION:
				ActionTransition actionTransition = (ActionTransition)transition;
				action(_ctx, actionTransition.ruleIndex, actionTransition.actionIndex);
				break;

			case Transition.PRECEDENCE:
				if (!precpred(_ctx, ((PrecedencePredicateTransition)transition).precedence)) {
					throw new FailedPredicateException(this, String.format("precpred(_ctx, %d)", ((PrecedencePredicateTransition)transition).precedence));
				}
				break;

			default:
				throw new UnsupportedOperationException("Unrecognized ATN transition type.");
		}

		setState(transition.target.stateNumber);
	}

	/** Method visitDecisionState() is called when the interpreter reaches
	 *  a decision state (instance of DecisionState). It gives an opportunity
	 *  for subclasses to track interesting things.
	 */
	protected int visitDecisionState(DecisionState p) {
		int predictedAlt = 1;
		if ( p.getNumberOfTransitions()>1 ) {
			getErrorHandler().sync(this);
			int decision = p.decision;
			if ( decision == overrideDecision && _input.index() == overrideDecisionInputIndex &&
			     !overrideDecisionReached )
			{
				predictedAlt = overrideDecisionAlt;

View on GitHub (pinned to 7d5770395b)

Solutions

1. Align versions: regenerate grammars with the exact tool version matching antlr4-runtime, and pin both in the build
2. Inspect the dependency tree for a stale antlr4-runtime (mvn dependency:tree / gradle dependencies) and exclude it
3. If interpreting external grammars, verify the serialized ATN's format version against the runtime's ATNDeserializer before executing

Example fix

// before
// build: antlr tool 4.13, runtime 4.7 pulled transitively
new ParserInterpreter(..., atn, ...).startRule();

// after (pom.xml)
<dependency>
  <groupId>org.antlr</groupId>
  <artifactId>antlr4-runtime</artifactId>
  <version>4.13.1</version> <!-- match the tool that generated/serialized the ATN -->
</dependency>

// before interpreting, confirm serialized ATN deserializes cleanly with this runtime
ATN atn;
try {
  atn = new ATNDeserializer().deserialize(serialized);
} catch (Exception e) {
  throw new IllegalStateException("ATN/runtime version mismatch", e);
}

try {
  parserInterpreter.startRule();
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("Unrecognized ATN transition")) {
    throw new IllegalStateException("ANTLR tool/runtime version mismatch — regenerate grammar", e);
  }
  throw e;
}

When it happens

Trigger: Deserializing a serialized ATN produced by a newer ANTLR tool whose transition kinds the current runtime's Transition classes don't map, then executing it with ParserInterpreter; hand-crafted or corrupted serialized ATN strings; classpath containing a stale antlr4-runtime ahead of the matching one.

Common situations: Mixed ANTLR versions on the classpath (tool 4.x vs runtime 4.y); grammar-interpreting utilities run against ATNs serialized by a different tool build; dependency convergence failures in Maven/Gradle pulling two runtime versions.

Related errors

• Unrecognized ATN transition type.
• precpred(_ctx, %d)
• Couldn't identify final state of the precedence rule prefix
• Could not deserialize ATN with version {0} (expected {1}).
• The specified transition type is not valid.

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