antlr/antlr4 · critical · Exception

The specified transition type: {} is not valid.

Error message

The specified transition type: {} is not valid.

What it means

While reading transitions from the serialized ATN, edgeFactory() maps a transition-type code to a constructor lambda. A code outside the known table (epsilon, range, rule, predicate, precedence-predicate, set, not-set, wildcard, action) raises this Exception. Unknown codes only appear when the data stream is misaligned or was produced by a tool version whose transition serialization the runtime does not understand.

Source

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

                        PredicateTransition(target, arg1, arg2, arg3 != 0),
                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
                        AtomTransition(target, Token.EOF) if arg3 != 0 else AtomTransition(target, arg1),
                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
                        ActionTransition(target, arg1, arg2, arg3 != 0),
                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
                        SetTransition(target, sets[arg1]),
                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
                        NotSetTransition(target, sets[arg1]),
                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
                        WildcardTransition(target),
                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
                        PrecedencePredicateTransition(target, arg1)
                      ]

    def edgeFactory(self, atn:ATN, type:int, src:int, trg:int, arg1:int, arg2:int, arg3:int, sets:list):
        target = atn.states[trg]
        if type > len(self.edgeFactories) or self.edgeFactories[type] is None:
            raise Exception("The specified transition type: " + str(type) + " is not valid.")
        else:
            return self.edgeFactories[type](atn, src, trg, arg1, arg2, arg3, sets, target)

    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()
                    ]

View on GitHub (pinned to 7d5770395b)

Solutions

1. Upgrade (or pin) the antlr4-python3-runtime to the exact version of the ANTLR tool that generated the code.
2. Regenerate all grammars in one pass with the single agreed version and commit everything together.
3. Check the embedded serialized ATN literal in the generated file is untouched.

try:
    lexer = MyLexer(stream)
except Exception as e:
    if 'transition 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() reading a transition type byte beyond the supported enum — after version skew shifted the cursor, from truncated/edited data, or from a newer tool's transition kinds not known to this runtime.

Common situations: ANTLR tool newer than the Python runtime (new transition kinds added in later serialized formats); regex-refactoring or copy-paste damage in generated Parser.py/Lexer.py; mixed artifacts from multiple generations.

Related errors

• Could not deserialize ATN with version {} (expected {}).
• The specified state 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/c27925aa87887052. Report an issue: GitHub.