{"record":{"id":"dfeeea9511abb13b","repo":"antlr/antlr4","slug":"could-not-deserialize-atn-with-version-expecte","errorCode":null,"errorMessage":"Could not deserialize ATN with version {} (expected {}).","messagePattern":"Could not deserialize ATN with version (.+?) \\(expected (.+?)\\)\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"critical","filePath":"runtime/Python3/src/antlr4/atn/ATNDeserializer.py","lineNumber":50,"sourceCode":"        self.readModes(atn)\n        sets = []\n        self.readSets(atn, sets)\n        self.readEdges(atn, sets)\n        self.readDecisions(atn)\n        self.readLexerActions(atn)\n        self.markPrecedenceDecisions(atn)\n        self.verifyATN(atn)\n        if self.deserializationOptions.generateRuleBypassTransitions \\\n                and atn.grammarType == ATNType.PARSER:\n            self.generateRuleBypassTransitions(atn)\n            # re-verify after modification\n            self.verifyATN(atn)\n        return atn\n\n    def checkVersion(self):\n        version = self.readInt()\n        if version != SERIALIZED_VERSION:\n            raise Exception(\"Could not deserialize ATN with version {} (expected {}).\".format(ord(version), SERIALIZED_VERSION))\n\n    def readATN(self):\n        idx = self.readInt()\n        grammarType = ATNType.fromOrdinal(idx)\n        maxTokenType = self.readInt()\n        return ATN(grammarType, maxTokenType)\n\n    def readStates(self, atn:ATN):\n        loopBackStateNumbers = []\n        endStateNumbers = []\n        nstates = self.readInt()\n        for i in range(0, nstates):\n            stype = self.readInt()\n            # ignore bad type of states\n            if stype==ATNState.INVALID_TYPE:\n                atn.addState(None)\n                continue\n            ruleIndex = self.readInt()","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/antlr/antlr4/blob/7d5770395bb7b02eb56e7c62662cb1d7c08f42a3/runtime/Python3/src/antlr4/atn/ATNDeserializer.py#L32-L68","documentation":"The serialized ATN every generated parser/lexer embeds starts with a format version stamp; the runtime refuses to deserialize data stamped with a different SERIALIZED_VERSION than the one it supports. This is the primary guard against tool/runtime version skew: a grammar generated by an older or newer ANTLR tool produces an ATN the runtime cannot safely interpret.","triggerScenarios":"ATNDeserializer.deserialize() on serialized ATN from a generated Lexer.py/Parser.py built by a different ANTLR tool version than the installed antlr4-python3-runtime package.","commonSituations":"Upgrading the pip runtime without regenerating parsers (or vice versa); vendoring generated files from another project; mixing antlr4ts/Java-generated artifacts with the Python runtime; CI using a pinned old runtime against freshly generated code.","solutions":["Align versions: regenerate all lexers/parsers with the ANTLR tool whose SERIALIZED_VERSION matches the installed Python runtime (check pip show antlr4-python3-runtime vs the tool jar version).","Pin both tool and runtime in your requirements/CI so they move together.","After regenerating, clean out stale generated files (*.interp, *.tokens, old Parser.py/Lexer.py) so an old artifact cannot be imported by accident."],"exampleFix":"# before: parser generated with ANTLR 4.7 tool, runtime 4.13 installed\n# -> Exception: Could not deserialize ATN with version ...\n\n# after: regenerate with matching tool and pin runtime\n# java -jar antlr-4.13.2-complete.jar -Dlanguage=Python3 MyGrammar.g4\n# pip install antlr4-python3-runtime==4.13.2","handlingStrategy":"try-catch","validationCode":"import antlr4\nfrom antlr4.atn.ATNDeserializer import SERIALIZED_VERSION\n# preflight: compare the version stamp embedded in your generated file's serialized ATN with the runtime's\nassert generated_serialized_atn[0] == chr(SERIALIZED_VERSION), 'regenerate grammar with ANTLR tool matching runtime %s' % antlr4.__version__","typeGuard":null,"tryCatchPattern":"try:\n    lexer = MyLexer(input_stream)\nexcept Exception as e:\n    if 'Could not deserialize ATN with version' in str(e):\n        raise RuntimeError('ANTLR tool/runtime version mismatch: regenerate parsers for runtime ' + antlr4.__version__)\n    raise","preventionTips":["Pin antlr4-python3-runtime to the exact version of the ANTLR tool in requirements and CI","Regenerate all artifacts together whenever either version changes","Fail fast at startup by constructing lexer and parser once as a self-test"],"tags":["antlr4","python","atn","version-mismatch","deserialization"],"backgroundTag":null,"analyzedSha":"7d5770395bb7b02eb56e7c62662cb1d7c08f42a3","analyzedAt":"2026-08-14T14:47:56.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}