{"record":{"id":"c18152e91a63e6f0","repo":"antlr/antlr4","slug":"could-not-deserialize-atn-with-version-d-expecte","errorCode":null,"errorMessage":"Could not deserialize ATN with version %d (expected %d).","messagePattern":"Could not deserialize ATN with version (.+?) \\(expected (.+?)\\)\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"critical","filePath":"runtime/Java/src/org/antlr/v4/runtime/atn/ATNDeserializer.java","lineNumber":56,"sourceCode":"\n\tpublic ATNDeserializer(ATNDeserializationOptions deserializationOptions) {\n\t\tif (deserializationOptions == null) {\n\t\t\tdeserializationOptions = ATNDeserializationOptions.getDefaultOptions();\n\t\t}\n\n\t\tthis.deserializationOptions = deserializationOptions;\n\t}\n\n\tpublic ATN deserialize(char[] data) {\n\t\treturn deserialize(decodeIntsEncodedAs16BitWords(data));\n\t}\n\n\tpublic ATN deserialize(int[] data) {\n\t\tint p = 0;\n\t\tint version = data[p++];\n\t\tif (version != SERIALIZED_VERSION) {\n\t\t\tString reason = String.format(Locale.getDefault(), \"Could not deserialize ATN with version %d (expected %d).\", version, SERIALIZED_VERSION);\n\t\t\tthrow new UnsupportedOperationException(new InvalidClassException(ATN.class.getName(), reason));\n\t\t}\n\n\t\tATNType grammarType = ATNType.values()[data[p++]];\n\t\tint maxTokenType = data[p++];\n\t\tATN atn = new ATN(grammarType, maxTokenType);\n\n\t\t//\n\t\t// STATES\n\t\t//\n\t\tList<Pair<LoopEndState, Integer>> loopBackStateNumbers = new ArrayList<Pair<LoopEndState, Integer>>();\n\t\tList<Pair<BlockStartState, Integer>> endStateNumbers = new ArrayList<Pair<BlockStartState, Integer>>();\n\t\tint nstates = data[p++];\n\t\tfor (int i=0; i<nstates; i++) {\n\t\t\tint stype = data[p++];\n\t\t\t// ignore bad type of states\n\t\t\tif ( stype==ATNState.INVALID_TYPE ) {\n\t\t\t\tatn.addState(null);\n\t\t\t\tcontinue;","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/antlr/antlr4/blob/7d5770395bb7b02eb56e7c62662cb1d7c08f42a3/runtime/Java/src/org/antlr/v4/runtime/atn/ATNDeserializer.java#L38-L74","documentation":"Serialized ATN data starts with a format version. This runtime expects ATNDeserializer.SERIALIZED_VERSION (4 in this source); if the generated or supplied serialized ATN carries a different version, it cannot be safely interpreted and UnsupportedOperationException wraps an InvalidClassException. The ATN never becomes usable with this runtime.","triggerScenarios":"Passing a _serializedATN string generated by a different ANTLR tool version; running generated parser classes from one release with an antlr4-runtime jar from another; manually loading serialized ATN bytes/chars from an incompatible source.","commonSituations":"Upgrading the runtime without regenerating parser/lexer sources, stale build output, dependency shading that selects an old runtime, or copying generated code between projects built with different ANTLR versions.","solutions":["Make the ANTLR generation tool and antlr4-runtime use the same release.","Regenerate all parser and lexer sources from the grammar, then clean-rebuild.","Inspect the dependency tree and remove duplicate/conflicting ANTLR runtime versions.","For custom serialized data, decode it and verify the first integer equals ATNDeserializer.SERIALIZED_VERSION before deserializing."],"exampleFix":"// before: parser generated by an older ANTLR tool\nnew MyParser(new CommonTokenStream(new MyLexer(input))).start();\n\n// after: regenerate MyLexer/MyParser with the same antlr version as the runtime, clean build outputs, then run\nMyParser parser = new MyParser(new CommonTokenStream(new MyLexer(input)));\nparser.start();","handlingStrategy":"validation","validationCode":"static boolean hasCompatibleAtnVersion(char[] serialized) {\n    int[] data = ATNDeserializer.decodeIntsEncodedAs16BitWords(serialized);\n    return data.length > 0 && data[0] == ATNDeserializer.SERIALIZED_VERSION;\n}","typeGuard":null,"tryCatchPattern":"try {\n    return new ATNDeserializer(options).deserialize(serialized);\n} catch (UnsupportedOperationException e) {\n    if (e.getCause() instanceof InvalidClassException) {\n        throw new IllegalStateException(\"Generated parser and ANTLR runtime versions differ; regenerate sources\", e);\n    }\n    throw e;\n}","preventionTips":["Pin the ANTLR tool and runtime to the same version.","Regenerate sources whenever either version changes.","Check for duplicate antlr4-runtime artifacts in dependencies."],"tags":["antlr","java","atn","serialization","version","compatibility"],"backgroundTag":null,"analyzedSha":"7d5770395bb7b02eb56e7c62662cb1d7c08f42a3","analyzedAt":"2026-08-14T14:47:56.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}