antlr/antlr4 · error · UnsupportedOperationException

The current parser does not support an ATN with bypass alter

Error message

The current parser does not support an ATN with bypass alternatives.

What it means

Parser.getATNWithBypassAlts() lazily builds a second ATN with bypass-alternative transitions (used by ParseTreePatternMatcher for '<tag>' wildcards) from the parser's serialized ATN. It raises UnsupportedOperationException when getSerializedATN() returns None, i.e., the recognizer does not carry the serialized ATN string that generated parsers embed.

Source

Thrown at runtime/Python3/src/antlr4/Parser.py:262

        return self._syntaxErrors

    def getTokenFactory(self):
        return self._input.tokenSource._factory

    # Tell our token source and error strategy about a new way to create tokens.#
    def setTokenFactory(self, factory:TokenFactory):
        self._input.tokenSource._factory = factory

    # The ATN with bypass alternatives is expensive to create so we create it
    # lazily.
    #
    # @throws UnsupportedOperationException if the current parser does not
    # implement the {@link #getSerializedATN()} method.
    #
    def getATNWithBypassAlts(self):
        serializedAtn = self.getSerializedATN()
        if serializedAtn is None:
            raise UnsupportedOperationException("The current parser does not support an ATN with bypass alternatives.")
        result = self.bypassAltsAtnCache.get(serializedAtn, None)
        if result is None:
            deserializationOptions = ATNDeserializationOptions()
            deserializationOptions.generateRuleBypassTransitions = True
            result = ATNDeserializer(deserializationOptions).deserialize(serializedAtn)
            self.bypassAltsAtnCache[serializedAtn] = result
        return result

    # The preferred method of getting a tree pattern. For example, here's a
    # sample use:
    #
    # <pre>
    # ParseTree t = parser.expr();
    # ParseTreePattern p = parser.compileParseTreePattern("&lt;ID&gt;+0", MyParser.RULE_expr);
    # ParseTreeMatch m = p.match(t);
    # String id = m.get("ID");
    # </pre>
    #

View on GitHub (pinned to 7d5770395b)

Solutions

1. Regenerate the parser with the ANTLR 4 tool so getSerializedATN() returns the embedded serialized ATN
2. If the parser is hand-written, implement getSerializedATN() to return the same string the tool would emit (or reuse the generated class instead)
3. For pure tree-pattern use, prefer a generated parser even in tests, since bypass-ATN construction is required

Example fix

# before
parser = MyHandWrittenParser(tokens)
pattern = parser.compileParseTreePattern("<ID>", MyHandWrittenParser.RULE_expr)  # raises

# after
from gen.MyParser import MyParser  # tool-generated, has serializedATN
parser = MyParser(tokens)
pattern = parser.compileParseTreePattern("<ID>", MyParser.RULE_expr)

# Python: confirm serialized ATN exists before pattern compilation
if parser.getSerializedATN() is None:
    raise ValueError("use a tool-generated parser for tree patterns")
pattern = parser.compileParseTreePattern("<ID>", rule_index, lexer)

# Python
def supports_bypass_atn(recognizer) -> bool:
    return recognizer.getSerializedATN() is not None

try:
    atn = parser.getATNWithBypassAlts()
except UnsupportedOperationException:
    # regenerate parser with the ANTLR tool, or implement getSerializedATN()
    raise

When it happens

Trigger: Calling compileParseTreePattern()/getTokenStream() utilities on a hand-written Parser subclass that never implements getSerializedATN(); a custom Recognizer base where the serialized ATN field was stripped; generated-code variants that store the ATN only as deserialized objects.

Common situations: Tree pattern matching or XPath on a manually created parser; using a parser class post-processed/minified to remove the big serialized-ATN string; mixing runtime versions where older generated parsers lack the expected serialization.

Related errors

• Parser can't discover a lexer to use
• The current parser does not support an ATN with bypass alter
• listener
• Unrecognized ATN transition type.
• The ATN must be a lexer ATN.

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