{"record":{"id":"cf32d861fdb10ced","repo":"antlr/antlr4","slug":"unrecognized-atn-transition-type","errorCode":null,"errorMessage":"Unrecognized ATN transition type.","messagePattern":"Unrecognized ATN transition type\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"runtime/Java/src/org/antlr/v4/runtime/ParserInterpreter.java","lineNumber":294,"sourceCode":"\t\t\t\tif (!sempred(_ctx, predicateTransition.ruleIndex, predicateTransition.predIndex)) {\n\t\t\t\t\tthrow new FailedPredicateException(this);\n\t\t\t\t}\n\n\t\t\t\tbreak;\n\n\t\t\tcase Transition.ACTION:\n\t\t\t\tActionTransition actionTransition = (ActionTransition)transition;\n\t\t\t\taction(_ctx, actionTransition.ruleIndex, actionTransition.actionIndex);\n\t\t\t\tbreak;\n\n\t\t\tcase Transition.PRECEDENCE:\n\t\t\t\tif (!precpred(_ctx, ((PrecedencePredicateTransition)transition).precedence)) {\n\t\t\t\t\tthrow new FailedPredicateException(this, String.format(\"precpred(_ctx, %d)\", ((PrecedencePredicateTransition)transition).precedence));\n\t\t\t\t}\n\t\t\t\tbreak;\n\n\t\t\tdefault:\n\t\t\t\tthrow new UnsupportedOperationException(\"Unrecognized ATN transition type.\");\n\t\t}\n\n\t\tsetState(transition.target.stateNumber);\n\t}\n\n\t/** Method visitDecisionState() is called when the interpreter reaches\n\t *  a decision state (instance of DecisionState). It gives an opportunity\n\t *  for subclasses to track interesting things.\n\t */\n\tprotected int visitDecisionState(DecisionState p) {\n\t\tint predictedAlt = 1;\n\t\tif ( p.getNumberOfTransitions()>1 ) {\n\t\t\tgetErrorHandler().sync(this);\n\t\t\tint decision = p.decision;\n\t\t\tif ( decision == overrideDecision && _input.index() == overrideDecisionInputIndex &&\n\t\t\t     !overrideDecisionReached )\n\t\t\t{\n\t\t\t\tpredictedAlt = overrideDecisionAlt;","sourceCodeStart":276,"sourceCodeEnd":312,"githubUrl":"https://github.com/antlr/antlr4/blob/7d5770395bb7b02eb56e7c62662cb1d7c08f42a3/runtime/Java/src/org/antlr/v4/runtime/ParserInterpreter.java#L276-L312","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Align versions: regenerate grammars with the exact tool version matching antlr4-runtime, and pin both in the build","Inspect the dependency tree for a stale antlr4-runtime (mvn dependency:tree / gradle dependencies) and exclude it","If interpreting external grammars, verify the serialized ATN's format version against the runtime's ATNDeserializer before executing"],"exampleFix":"// before\n// build: antlr tool 4.13, runtime 4.7 pulled transitively\nnew ParserInterpreter(..., atn, ...).startRule();\n\n// after (pom.xml)\n<dependency>\n  <groupId>org.antlr</groupId>\n  <artifactId>antlr4-runtime</artifactId>\n  <version>4.13.1</version> <!-- match the tool that generated/serialized the ATN -->\n</dependency>","handlingStrategy":"try-catch","validationCode":"// before interpreting, confirm serialized ATN deserializes cleanly with this runtime\nATN atn;\ntry {\n  atn = new ATNDeserializer().deserialize(serialized);\n} catch (Exception e) {\n  throw new IllegalStateException(\"ATN/runtime version mismatch\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n  parserInterpreter.startRule();\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage().contains(\"Unrecognized ATN transition\")) {\n    throw new IllegalStateException(\"ANTLR tool/runtime version mismatch — regenerate grammar\", e);\n  }\n  throw e;\n}","preventionTips":["Pin antlr4 tool and antlr4-runtime to identical versions in the build","Audit the dependency tree for transitively pulled stale runtimes","Prefer generated parsers over runtime interpretation for external grammars"],"tags":["antlr","parser-interpreter","version-mismatch","atn","classloading"],"backgroundTag":null,"analyzedSha":"7d5770395bb7b02eb56e7c62662cb1d7c08f42a3","analyzedAt":"2026-08-14T14:47:56.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}