antlr/antlr4 · critical · Exception

The specified state type {} is not valid.

Error message

The specified state type {} is not valid.

What it means

Symmetric to the transition factory: stateFactory() maps state-type codes (basic, rule start/stop, block start/end, loop variants, tokens start) to constructors. An out-of-table code raises this Exception, again indicating the serialized stream does not match what this runtime knows how to read.

Source

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

    stateFactories = [  lambda : None,
                        lambda : BasicState(),
                        lambda : RuleStartState(),
                        lambda : BasicBlockStartState(),
                        lambda : PlusBlockStartState(),
                        lambda : StarBlockStartState(),
                        lambda : TokensStartState(),
                        lambda : RuleStopState(),
                        lambda : BlockEndState(),
                        lambda : StarLoopbackState(),
                        lambda : StarLoopEntryState(),
                        lambda : PlusLoopbackState(),
                        lambda : LoopEndState()
                    ]

    def stateFactory(self, type:int, ruleIndex:int):
        if type> len(self.stateFactories) or self.stateFactories[type] is None:
            raise Exception("The specified state type " + str(type) + " is not valid.")
        else:
            s = self.stateFactories[type]()
            if s is not None:
                s.ruleIndex = ruleIndex
        return s

    CHANNEL = 0     #The type of a {@link LexerChannelAction} action.
    CUSTOM = 1      #The type of a {@link LexerCustomAction} action.
    MODE = 2        #The type of a {@link LexerModeAction} action.
    MORE = 3        #The type of a {@link LexerMoreAction} action.
    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),

View on GitHub (pinned to 7d5770395b)

Solutions

1. Match ANTLR tool and Python runtime versions and regenerate everything.
2. Purge old generated artifacts (*.py, *.tokens, *.interp) and regenerate from scratch.
3. Vendor generated files per-version in separate directories so mixed imports cannot occur.

try:
    parser = MyParser(tokens)
except Exception as e:
    if 'state type' in str(e):
        raise RuntimeError('serialized ATN format not supported by this runtime: align ANTLR tool and runtime versions')
    raise

When it happens

Trigger: deserialize() encountering a state type code not in the runtime's stateFactories table — misaligned data stream from version mismatch or corrupted generated file.

Common situations: Tool/runtime version skew (state kinds were added/renumbered across serialized format revisions); stale or hand-edited generated files; importing generated code from a project built with a different ANTLR release.

Related errors

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

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