{"record":{"id":"f859fc8af6404666","repo":"antlr/antlr4","slug":"the-specified-state-type-0-is-not-valid","errorCode":null,"errorMessage":"The specified state type {0} is not valid.","messagePattern":"The specified state type (.+?) is not valid\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"critical","filePath":"runtime/CSharp/src/Atn/ATNDeserializer.cs","lineNumber":1119,"sourceCode":"                    break;\n                }\n\n                case StateType.PlusLoopBack:\n                {\n                    s = new PlusLoopbackState();\n                    break;\n                }\n\n                case StateType.LoopEnd:\n                {\n                    s = new LoopEndState();\n                    break;\n                }\n\n                default:\n                {\n                    string message = string.Format(CultureInfo.CurrentCulture, \"The specified state type {0} is not valid.\", type);\n                    throw new ArgumentException(message);\n                }\n            }\n            s.ruleIndex = ruleIndex;\n            return s;\n        }\n\n        protected internal virtual ILexerAction LexerActionFactory(LexerActionType type, int data1, int data2)\n        {\n            switch (type)\n            {\n                case LexerActionType.Channel:\n                {\n                    return new LexerChannelAction(data1);\n                }\n\n                case LexerActionType.Custom:\n                {\n                    return new LexerCustomAction(data1, data2);","sourceCodeStart":1101,"sourceCodeEnd":1137,"githubUrl":"https://github.com/antlr/antlr4/blob/7d5770395bb7b02eb56e7c62662cb1d7c08f42a3/runtime/CSharp/src/Atn/ATNDeserializer.cs#L1101-L1137","documentation":"Thrown by ATNDeserializer.StateFactory when the serialized ATN contains a state type value that does not match any known StateType (Basic, RuleStop, BlockStart, PlusBlockStart, StarBlockStart, PlusLoopback, StarLoopback, LoopEnd, BlockEnd, etc.). The ATN is the serialized automaton embedded in generated recognizer code; an unknown state type means the bytes being deserialized are not a valid ATN. In practice this indicates data corruption or a mismatch between the generated code's serialized ATN and the runtime version reading it.","triggerScenarios":"The runtime deserializes the static ATNSERIALIZED string (or custom ATN data passed to ATNDeserializer.Deserialize) and hits a state-type byte outside the known enum values. Happens when generated parser/lexer code was produced by an ANTLR tool version whose serialization format differs from the runtime, when the serialized ATN array was manually edited or truncated, or when a custom IIntStream/char source feeds garbage into deserialization.","commonSituations":"Upgrading the Antlr4.Runtime NuGet package without regenerating parser/lexer code (or vice versa); hand-modifying the generated *_ATN constants; merging generated files across branches causing partial corruption; mixing runtimes (e.g. Java-format serialized ATN fed to the C# runtime).","solutions":["Regenerate the parser and lexer from the .g4 grammar using the exact ANTLR tool version that matches the Antlr4.Runtime package version in the project","Verify the Antlr4.Runtime NuGet version and the ANTLR tool version used by the codegen build target (they must be the same 4.x line)","Delete and re-create generated files (e.g. via a clean rebuild of the Antlr4 codegen MSBuild target) instead of editing the *_ATN constants by hand","If passing a custom serialized ATN array, validate it was produced by the same tool version before calling ATNDeserializer.Deserialize"],"exampleFix":"// before: generated code from ANTLR 4.7, runtime package 4.13\nvar lexer = new MyLexer(input); // throws ArgumentException from ATNDeserializer\n\n// after: regenerate with the matching tool and use the matching runtime\n// (build) regenerate MyLexer.g4 with antlr-4.13.1-complete.jar / Antlr4.Codegen 4.13.1\nvar lexer = new MyLexer(input);","handlingStrategy":"validation","validationCode":"// Before constructing a recognizer with a custom serialized ATN, sanity-check the source pair\nint[] serialized = LoadSerializedAtn();\nif (serialized == null || serialized.Length == 0)\n    throw new InvalidOperationException(\"Serialized ATN is missing or empty; regenerate parser sources.\");","typeGuard":"static bool LooksLikeAtnData(int[] s) => s != null && s.Length >= 4 && s[0] >= 0 && s[0] <= 4; /* serializedATNFormat header */","tryCatchPattern":null,"preventionTips":["Pin the Antlr4.Runtime NuGet package and the ANTLR codegen tool to the same version in one place (e.g. Directory.Build.props)","Regenerate all parser/lexer sources in CI whenever either version bumps","Never hand-edit the generated serialized ATN constants; treat generated files as build artifacts"],"tags":["antlr","csharp","atn","deserialization","version-mismatch"],"backgroundTag":null,"analyzedSha":"7d5770395bb7b02eb56e7c62662cb1d7c08f42a3","analyzedAt":"2026-08-14T14:47:56.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}