{"record":{"id":"22c0322a41a3e2cf","repo":"antlr/antlr4","slug":"unrecognized-atn-transition-type-22c032","errorCode":null,"errorMessage":"Unrecognized ATN transition type.","messagePattern":"Unrecognized ATN transition type\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"runtime/Python3/src/antlr4/ParserInterpreter.py","lineNumber":156,"sourceCode":"                self.enterRule(ctx, transition.target.stateNumber, ruleIndex)\n\n        elif tt==Transition.PREDICATE:\n\n            if not self.sempred(self._ctx, transition.ruleIndex, transition.predIndex):\n                raise FailedPredicateException(self)\n\n        elif tt==Transition.ACTION:\n\n            self.action(self._ctx, transition.ruleIndex, transition.actionIndex)\n\n        elif tt==Transition.PRECEDENCE:\n\n            if not self.precpred(self._ctx, transition.precedence):\n                msg = \"precpred(_ctx, \" + str(transition.precedence) + \")\"\n                raise FailedPredicateException(self, msg)\n\n        else:\n            raise UnsupportedOperationException(\"Unrecognized ATN transition type.\")\n\n        self.state = transition.target.stateNumber\n\n    def visitRuleStopState(self, p:ATNState):\n        ruleStartState = self.atn.ruleToStartState[p.ruleIndex]\n        if ruleStartState.isPrecedenceRule:\n            parentContext = self._parentContextStack.pop()\n            self.unrollRecursionContexts(parentContext.a)\n            self.state = parentContext[1]\n        else:\n            self.exitRule()\n\n        ruleTransition = self.atn.states[self.state].transitions[0]\n        self.state = ruleTransition.followState.stateNumber\n","sourceCodeStart":138,"sourceCodeEnd":171,"githubUrl":"https://github.com/antlr/antlr4/blob/7d5770395bb7b02eb56e7c62662cb1d7c08f42a3/runtime/Python3/src/antlr4/ParserInterpreter.py#L138-L171","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Align versions: regenerate all grammars with the same ANTLR tool version as the installed runtime (pip show antlr4-python3-runtime)","Pin the runtime version in requirements.txt to the version that matches your generated code","If you build ATNs yourself, restrict transitions to the types visitState handles or extend visitState in a subclass"],"exampleFix":"# before\n# grammar generated with ANTLR 4.7, runtime 4.13 installed:\ninterp = ParserInterpreter(..., atn_from_4_7, tokens)\ntree = interp.parse(0)  # UnsupportedOperationException on unknown transition\n\n# after\n# regenerate with 4.13: $ antlr4 -Dlanguage=Python3 MyGrammar.g4\n# then pin: antlr4-python3-runtime==4.13.*\ninterp = ParserInterpreter(..., atn_from_4_13, tokens)","handlingStrategy":"fallback","validationCode":"# Python: verify tool/runtime lineage before interpreting\nimport antlr4\nassert atn_source_version == antlr4.__version__.rsplit('.', 1)[0], \"ATN and runtime versions differ\"","typeGuard":null,"tryCatchPattern":"from antlr4.error.Errors import UnsupportedOperationException\ntry:\n    tree = interpreter.parse(start_rule)\nexcept UnsupportedOperationException as ex:\n    if \"Unrecognized ATN transition\" in str(ex):\n        # fall back to the generated parser compiled from the same grammar version\n        tree = GeneratedParser(tokens).startRule()\n    else:\n        raise","preventionTips":["Regenerate grammars with the exact tool version matching your runtime","Pin antlr4-python3-runtime in requirements.txt alongside the tool version","Run an interpreter smoke test in CI to catch serialization-format drift early"],"tags":["antlr","python","parser-interpreter","atn","version-mismatch"],"backgroundTag":null,"analyzedSha":"7d5770395bb7b02eb56e7c62662cb1d7c08f42a3","analyzedAt":"2026-08-14T14:47:56.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}