antlr/antlr4 · error · UnsupportedOperationException

Unrecognized ATN transition type.

Error message

Unrecognized ATN transition type.

What it means

ParserInterpreter.visitState dispatches on the transition type of each ATN edge (RULE, PREDICATE, ACTION, PRECEDENCE, plus the basic label/epsilon/set handling above); an edge whose type matches none of the known cases raises UnsupportedOperationException('Unrecognized ATN transition type.'). In practice this signals an ATN whose shape does not match what this runtime's interpreter can walk — most often a serialized-ATN/version mismatch.

Source

Thrown at runtime/Python3/src/antlr4/ParserInterpreter.py:156

                self.enterRule(ctx, transition.target.stateNumber, ruleIndex)

        elif tt==Transition.PREDICATE:

            if not self.sempred(self._ctx, transition.ruleIndex, transition.predIndex):
                raise FailedPredicateException(self)

        elif tt==Transition.ACTION:

            self.action(self._ctx, transition.ruleIndex, transition.actionIndex)

        elif tt==Transition.PRECEDENCE:

            if not self.precpred(self._ctx, transition.precedence):
                msg = "precpred(_ctx, " + str(transition.precedence) + ")"
                raise FailedPredicateException(self, msg)

        else:
            raise UnsupportedOperationException("Unrecognized ATN transition type.")

        self.state = transition.target.stateNumber

    def visitRuleStopState(self, p:ATNState):
        ruleStartState = self.atn.ruleToStartState[p.ruleIndex]
        if ruleStartState.isPrecedenceRule:
            parentContext = self._parentContextStack.pop()
            self.unrollRecursionContexts(parentContext.a)
            self.state = parentContext[1]
        else:
            self.exitRule()

        ruleTransition = self.atn.states[self.state].transitions[0]
        self.state = ruleTransition.followState.stateNumber

View on GitHub (pinned to 7d5770395b)

Solutions

1. Align versions: regenerate all grammars with the same ANTLR tool version as the installed runtime (pip show antlr4-python3-runtime)
2. Pin the runtime version in requirements.txt to the version that matches your generated code
3. If you build ATNs yourself, restrict transitions to the types visitState handles or extend visitState in a subclass

Example fix

# before
# grammar generated with ANTLR 4.7, runtime 4.13 installed:
interp = ParserInterpreter(..., atn_from_4_7, tokens)
tree = interp.parse(0)  # UnsupportedOperationException on unknown transition

# after
# regenerate with 4.13: $ antlr4 -Dlanguage=Python3 MyGrammar.g4
# then pin: antlr4-python3-runtime==4.13.*
interp = ParserInterpreter(..., atn_from_4_13, tokens)

# Python: verify tool/runtime lineage before interpreting
import antlr4
assert atn_source_version == antlr4.__version__.rsplit('.', 1)[0], "ATN and runtime versions differ"

from antlr4.error.Errors import UnsupportedOperationException
try:
    tree = interpreter.parse(start_rule)
except UnsupportedOperationException as ex:
    if "Unrecognized ATN transition" in str(ex):
        # fall back to the generated parser compiled from the same grammar version
        tree = GeneratedParser(tokens).startRule()
    else:
        raise

When it happens

Trigger: Loading a serialized ATN produced by a different ANTLR tool version and driving it with ParserInterpreter; deserializing with non-default ATNDeserializationOptions that introduce transitions the interpreter's visitor lacks; upgrading the runtime package without regenerating grammars.

Common situations: Generated parser or serialized ATN from a newer/older ANTLR than the installed antlr4-python3-runtime (e.g., ATN serialization format changes across major versions); hand-built or transformed ATNs fed to ParserInterpreter; custom Transition subclasses the interpreter never learned.

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/22c0322a41a3e2cf. Report an issue: GitHub.