antlr/antlr4 · critical · ArgumentException

The specified state type {0} is not valid.

Error message

The specified state type {0} is not valid.

What it means

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.

Source

Thrown at runtime/CSharp/src/Atn/ATNDeserializer.cs:1119

                    break;
                }

                case StateType.PlusLoopBack:
                {
                    s = new PlusLoopbackState();
                    break;
                }

                case StateType.LoopEnd:
                {
                    s = new LoopEndState();
                    break;
                }

                default:
                {
                    string message = string.Format(CultureInfo.CurrentCulture, "The specified state type {0} is not valid.", type);
                    throw new ArgumentException(message);
                }
            }
            s.ruleIndex = ruleIndex;
            return s;
        }

        protected internal virtual ILexerAction LexerActionFactory(LexerActionType type, int data1, int data2)
        {
            switch (type)
            {
                case LexerActionType.Channel:
                {
                    return new LexerChannelAction(data1);
                }

                case LexerActionType.Custom:
                {
                    return new LexerCustomAction(data1, data2);

View on GitHub (pinned to 7d5770395b)

Solutions

1. 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
2. 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)
3. 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
4. If passing a custom serialized ATN array, validate it was produced by the same tool version before calling ATNDeserializer.Deserialize

Example fix

// before: generated code from ANTLR 4.7, runtime package 4.13
var lexer = new MyLexer(input); // throws ArgumentException from ATNDeserializer

// after: regenerate with the matching tool and use the matching runtime
// (build) regenerate MyLexer.g4 with antlr-4.13.1-complete.jar / Antlr4.Codegen 4.13.1
var lexer = new MyLexer(input);

// Before constructing a recognizer with a custom serialized ATN, sanity-check the source pair
int[] serialized = LoadSerializedAtn();
if (serialized == null || serialized.Length == 0)
    throw new InvalidOperationException("Serialized ATN is missing or empty; regenerate parser sources.");

static bool LooksLikeAtnData(int[] s) => s != null && s.Length >= 4 && s[0] >= 0 && s[0] <= 4; /* serializedATNFormat header */

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• The specified lexer action type {0} is not valid.
• Couldn't identify final state of the precedence rule prefix
• Could not deserialize ATN with version {0} (expected {1}).
• The specified transition type is not valid.
• Unrecognized ATN transition type.

AI-assisted analysis of antlr/antlr4@7d5770395b (2026-08-14). Data as JSON: /api/errors/f859fc8af6404666. Report an issue: GitHub.