antlr/antlr4 · critical · IllegalArgumentException

The specified transition type is not valid.

Error message

The specified transition type is not valid.

What it means

While reading serialized edges, ATNDeserializer.edgeFactory maps transition type codes 1..10 to the known Transition classes (EPSILON through PRECEDENCE). Any other value means the integer stream is not a valid ATN edge table for this format and is rejected with IllegalArgumentException.

Source

Thrown at runtime/Java/src/org/antlr/v4/runtime/atn/ATNDeserializer.java:531

				return pt;
			case Transition.PRECEDENCE:
				return new PrecedencePredicateTransition(target, arg1);
			case Transition.ATOM :
				if (arg3 != 0) {
					return new AtomTransition(target, Token.EOF);
				}
				else {
					return new AtomTransition(target, arg1);
				}
			case Transition.ACTION :
				ActionTransition a = new ActionTransition(target, arg1, arg2, arg3 != 0);
				return a;
			case Transition.SET : return new SetTransition(target, sets.get(arg1));
			case Transition.NOT_SET : return new NotSetTransition(target, sets.get(arg1));
			case Transition.WILDCARD : return new WildcardTransition(target);
		}

		throw new IllegalArgumentException("The specified transition type is not valid.");
	}

	protected ATNState stateFactory(int type, int ruleIndex) {
		ATNState s;
		switch (type) {
			case ATNState.INVALID_TYPE: return null;
			case ATNState.BASIC : s = new BasicState(); break;
			case ATNState.RULE_START : s = new RuleStartState(); break;
			case ATNState.BLOCK_START : s = new BasicBlockStartState(); break;
			case ATNState.PLUS_BLOCK_START : s = new PlusBlockStartState(); break;
			case ATNState.STAR_BLOCK_START : s = new StarBlockStartState(); break;
			case ATNState.TOKEN_START : s = new TokensStartState(); break;
			case ATNState.RULE_STOP : s = new RuleStopState(); break;
			case ATNState.BLOCK_END : s = new BlockEndState(); break;
			case ATNState.STAR_LOOP_BACK : s = new StarLoopbackState(); break;
			case ATNState.STAR_LOOP_ENTRY : s = new StarLoopEntryState(); break;
			case ATNState.PLUS_LOOP_BACK : s = new PlusLoopbackState(); break;
			case ATNState.LOOP_END : s = new LoopEndState(); break;

View on GitHub (pinned to 7d5770395b)

Solutions

1. Use serialized data produced by the matching ATNSerializer/ANTLR tool version.
2. Regenerate lexer/parser sources and clean-build.
3. Eliminate conflicting ANTLR runtime versions on the classpath.
4. Do not modify, truncate, or re-encode the generated serialized ATN.

Example fix

// before
ATN atn = new ATNDeserializer().deserialize(modifiedSerializedAtn.toCharArray());

// after: regenerate serialized ATN with the same tool/runtime and pass it unchanged
ATN atn = new ATNDeserializer().deserialize(MyLexer._serializedATN.toCharArray());

try {
    return new ATNDeserializer(options).deserialize(serialized);
} catch (IllegalArgumentException e) {
    throw new IllegalArgumentException("Serialized ATN transition table is corrupt or incompatible", e);
}

When it happens

Trigger: Deserializing corrupted/truncated serialized ATN data; manually changing the serialized integer sequence so edge records become misaligned; or supplying data produced by an incompatible serializer/runtime pair.

Common situations: Mixed ANTLR tool/runtime versions, hand-edited generated _serializedATN strings, custom ATN serialization experiments, and partial copies of serialized data.

Related errors

• Could not deserialize ATN with version %d (expected %d).
• Couldn't identify final state of the precedence rule prefix
• The specified state type %d is not valid.
• Serialized ATN data element[i] = v doesn't fit in 31 bits
• Cannot serialize a transition to a removed state.

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