antlr/antlr4 · critical · NotSupportedException

Could not deserialize ATN with version {0} (expected {1}).

Error message

Could not deserialize ATN with version {0} (expected {1}).

What it means

ATNDeserializer.CheckVersion reads a leading version int from the serialized ATN and compares it to SerializedVersion. A mismatch throws NotSupportedException with both numbers — the serialized ATN is from an incompatible ANTLR version and cannot be interpreted by this runtime.

Source

Thrown at runtime/CSharp/src/Atn/ATNDeserializer.cs:454

				int stateNumber = ReadInt();
				((RuleStartState)atn.states[stateNumber]).isPrecedenceRule = true;
			}
		}

		protected internal virtual ATN ReadATN()
		{
			ATNType grammarType = (ATNType)ReadInt();
			int maxTokenType = ReadInt();
			return new ATN(grammarType, maxTokenType);
		}

		protected internal virtual void CheckVersion()
		{
			int version = ReadInt();
			if (version != SerializedVersion)
			{
				string reason = string.Format(CultureInfo.CurrentCulture, "Could not deserialize ATN with version {0} (expected {1}).", version, SerializedVersion);
				throw new NotSupportedException(reason);
			}
		}

        /// <summary>
        /// Analyze the
        /// <see cref="StarLoopEntryState"/>
        /// states in the specified ATN to set
        /// the
        /// <see cref="StarLoopEntryState.isPrecedenceDecision"/>
        /// field to the
        /// correct value.
        /// </summary>
        /// <param name="atn">The ATN.</param>
        protected internal virtual void MarkPrecedenceDecisions(ATN atn)
        {
            foreach (ATNState state in atn.states)
            {
                if (!(state is StarLoopEntryState))

View on GitHub (pinned to 7d5770395b)

Solutions

1. Regenerate the parser with the ANTLR tool version that matches the runtime package exactly
2. Pin both the codegen Maven/NuGet build-time package and the runtime to the same version
3. Delete old generated files so regeneration is guaranteed

try { new ATNDeserializer().Deserialize(data); } catch (NotSupportedException e) { /* parse 'version X (expected Y)' from message; align tool and runtime versions */ }

When it happens

Trigger: Generated parser .cs files containing a serialized ATN from ANTLR 4.x being loaded by a runtime whose SerializedVersion differs (e.g. ATN format changed across major/minor releases).

Common situations: Upgrading the Antlr4.Runtime NuGet package without regenerating parsers (or vice versa); generated code checked in from a teammate using a different tool version.

Related errors

• Couldn't identify final state of the precedence rule prefix
• The specified transition type is not valid.
• The specified state type {0} is not valid.
• The specified lexer action type {0} is not valid.
• Unrecognized ATN transition type.

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