antlr/antlr4 · critical · Exception

The specified lexer action type {} is not valid.

Error message

The specified lexer action type {} is not valid.

What it means

lexerActionFactory() decodes lexer action codes (channel, custom, mode, more, popMode, pushMode, skip, type) when a lexer ATN executes or deserializes action transitions. An unknown action type code raises this Exception — in practice always a symptom of serialized data deserialized by an incompatible runtime version, since the code table is fixed per format version.

Source

Thrown at runtime/Python3/src/antlr4/atn/ATNDeserializer.py:444

    POP_MODE = 4    #The type of a {@link LexerPopModeAction} action.
    PUSH_MODE = 5   #The type of a {@link LexerPushModeAction} action.
    SKIP = 6        #The type of a {@link LexerSkipAction} action.
    TYPE = 7        #The type of a {@link LexerTypeAction} action.

    actionFactories = [ lambda data1, data2: LexerChannelAction(data1),
                        lambda data1, data2: LexerCustomAction(data1, data2),
                        lambda data1, data2: LexerModeAction(data1),
                        lambda data1, data2: LexerMoreAction.INSTANCE,
                        lambda data1, data2: LexerPopModeAction.INSTANCE,
                        lambda data1, data2: LexerPushModeAction(data1),
                        lambda data1, data2: LexerSkipAction.INSTANCE,
                        lambda data1, data2: LexerTypeAction(data1)
                      ]

    def lexerActionFactory(self, type:int, data1:int, data2:int):

        if type > len(self.actionFactories) or self.actionFactories[type] is None:
            raise Exception("The specified lexer action type " + str(type) + " is not valid.")
        else:
            return self.actionFactories[type](data1, data2)

View on GitHub (pinned to 7d5770395b)

Solutions

1. Regenerate lexer and parser together with the tool version matching the runtime.
2. Upgrade the runtime package to the tool's version (pip install antlr4-python3-runtime==<tool version>).
3. Clean build outputs so no pre-regeneration lexer artifact survives.

try:
    lexer = MyLexer(stream)
except Exception as e:
    if 'lexer action type' in str(e):
        raise RuntimeError('lexer ATN uses actions this runtime cannot decode: regenerate with matching versions')
    raise

When it happens

Trigger: deserialize() (or first lex) reading a lexer action opcode beyond the supported table because the data stream is misaligned or from a different serialized-version grammar (e.g. a grammar with lexer actions generated by a newer tool).

Common situations: Grammars using -> channel/mode/type/skip/custom actions combined with tool/runtime version mismatch; stale generated lexer files; partial regeneration (new lexer, old parser or vice versa).

Related errors

• Could not deserialize ATN with version {} (expected {}).
• The specified transition type: {} is not valid.
• The specified state type {} is not valid.
• The specified lexer action type {0} is not valid.
• IllegalState

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