antlr/antlr4 · critical · ArgumentException

The specified lexer action type {0} is not valid.

Error message

The specified lexer action type {0} is not valid.

What it means

Thrown by ATNDeserializer.LexerActionFactory when the serialized ATN contains a lexer action type byte that does not correspond to any known LexerActionType (Channel, Custom, Mode, More, PushMode, PopMode, Skip, Type). Lexer actions are the skip(), mode(), more(), channel(), type() commands compiled into lexer rules; an unknown action type means the serialized ATN data is not one this runtime knows how to turn into ILexerAction instances.

Source

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

                case LexerActionType.PushMode:
                {
                    return new LexerPushModeAction(data1);
                }

                case LexerActionType.Skip:
                {
                    return LexerSkipAction.Instance;
                }

                case LexerActionType.Type:
                {
                    return new LexerTypeAction(data1);
                }

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

View on GitHub (pinned to 7d5770395b)

Solutions

1. Align the ANTLR codegen tool version and the Antlr4.Runtime NuGet package to the same release, then regenerate all lexer/parser sources
2. Restore the generated lexer file from source control if the serialized ATN constant was modified or partially merged
3. If you construct the ATN yourself, check every lexer action opcode you emit against the LexerActionType enum supported by the runtime you ship

Example fix

// before
// lexer generated by antlr tool 4.13, runtime pinned to 4.6.6
var interp = new LexerInterpreter(name, vocab, rules, modes, atn, input); // throws

// after
// pin both to the same version and regenerate
// <PackageReference Include="Antlr4.Runtime" Version="4.13.1" /> + Antlr4.Codegen 4.13.1

// Before interpreting a serialized ATN, verify producer/runtime versions agree
if (GeneratedAtn.ToolVersion != RuntimeVersionInfo.ThisRuntime)
    throw new InvalidOperationException($"ATN built by {GeneratedAtn.ToolVersion}, runtime is {RuntimeVersionInfo.ThisRuntime}; regenerate sources.");

When it happens

Trigger: Deserializing a serialized ATN whose lexer-action opcode byte falls outside the recognized enum, i.e. the default branch of LexerActionFactory's switch. Occurs with a tool/runtime version mismatch (a newer tool emitted a new action opcode the older runtime does not know), corrupted generated ATN constants, or a hand-built serialized ATN array with an invalid action opcode.

Common situations: Upgrading the ANTLR codegen tool but not the runtime (or the reverse); editing generated lexer files manually; using a serialized ATN produced for a different language runtime whose action encoding differs.

Related errors

• The specified state 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.
• Precedence predicates are not supported in lexers.

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