What causes "target cannot be null." in antlr/antlr4?

Create the target ATNState before creating the transition that points to it

antlr/antlr4 · error · ArgumentNullException

target cannot be null.

Error message

target cannot be null.

What it means

The abstract Transition constructor requires a non-null target state; every edge in an ATN must point somewhere. The runtime checks this at construction time and throws ArgumentNullException otherwise. This is internal/runtime-level API: user code almost never constructs transitions directly, so seeing this error usually means code is hand-building or mutating ATN structures.

Source

Thrown at runtime/CSharp/src/Atn/Transition.cs:37

    /// we can fix these transitions as specific classes. The DFA transitions
    /// on the other hand need to update the labels as it adds transitions to
    /// the states. We'll use the term Edge for the DFA to distinguish them from
    /// ATN transitions.</p>
    /// </remarks>
    public abstract class Transition
    {
        public static readonly ReadOnlyCollection<string> serializationNames = new ReadOnlyCollection<string>(Arrays.AsList("INVALID", "EPSILON", "RANGE", "RULE", "PREDICATE", "ATOM", "ACTION", "SET", "NOT_SET", "WILDCARD", "PRECEDENCE"));

        /// <summary>The target of this transition.</summary>
        /// <remarks>The target of this transition.</remarks>
        [NotNull]
        public ATNState target;

        protected internal Transition(ATNState target)
        {
            if (target == null)
            {
                throw new ArgumentNullException("target cannot be null.");
            }
            this.target = target;
        }

        public abstract TransitionType TransitionType
        {
            get;
        }

        /// <summary>Determines if the transition is an "epsilon" transition.</summary>
        /// <remarks>
        /// Determines if the transition is an "epsilon" transition.
        /// <p>The default implementation returns
        /// <see langword="false"/>
        /// .</p>
        /// </remarks>
        /// <returns>
        ///

View on GitHub (pinned to 7d5770395b)

Solutions

Create the target ATNState before creating the transition that points to it
If building transitions from data, validate targetState != null before the constructor call and report which edge index was malformed
Prefer mutating an existing deserialized ATN over constructing one from scratch

Example fix

// before
var t = new AtomTransition(null, label);

// after
var target = new BasicState { ruleIndex = 0 };
atn.AddState(target);
var t = new AtomTransition(target, label);

Defensive patterns

Strategy: validation

Validate before calling

ATNState target = GetTargetState() ?? throw new InvalidOperationException($"Edge {edgeIndex} has no target state");
atn.AddState(target);
var t = new AtomTransition(target, label);

Type guard

static bool IsValidTransitionTarget(ATNState s) => s != null && s.stateNumber >= 0;

Prevention

When hand-building ATNs, create and register all states before any transitions
Validate edge data (from,to both present) before constructing transitions in custom deserializers

When it happens

Trigger: Calling any Transition subclass constructor (AtomTransition, RangeTransition, SetTransition, RuleTransition, etc.) with target == null. Happens in custom ATN construction, test code that builds ATNs by hand, or code that copies/rewires transitions and passes a null target.

Common situations: Writing a custom serializer/deserializer or ATN optimizer; cloning ATNs; test harnesses synthesizing small ATNs and forgetting to create the target state first.

Related errors

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