antlr/antlr4 · error · ArgumentNullException

{parameterName}

Error message

{parameterName}

What it means

Misc.Args.NotNull(parameterName, value) is the runtime's central null-argument guard, used by many public APIs (recognizers, simulators, ATN deserializer, interpreters). It throws ArgumentNullException whose message is just the parameter name passed in — so the 'error message' you see is a parameter name like 'atn', 'input', or 'decisionState', not a sentence. This is a fail-fast contract check: the called API cannot do anything sensible with a null argument.

Source

Thrown at runtime/CSharp/src/Misc/Args.cs:23

using System;

namespace Antlr4.Runtime.Misc
{
    /// <author>Sam Harwell</author>
    public static class Args
    {
        /// <exception cref="System.ArgumentNullException">
        /// if
        /// <paramref name="value"/>
        /// is
        /// <see langword="null"/>
        /// .
        /// </exception>
        public static void NotNull(string parameterName, object value)
        {
            if (value == null)
            {
                throw new ArgumentNullException(parameterName);
            }
        }
    }
}

View on GitHub (pinned to 7d5770395b)

Solutions

1. Read the exception message: it names the exact parameter that was null (e.g. 'atn', 'input') — fix the corresponding argument at the call site
2. Coalesce nullable inputs before calling the runtime API (value ?? fallback or throw your own descriptive exception)
3. Register/initialize every dependency (streams, vocabularies, listeners) before constructing runtime objects

Example fix

// before
var interp = new ParserInterpreter(grammarFileName, vocabulary, null /*ruleNames*/, atn, input);
// -> ArgumentNullException with message "ruleNames"

// after
var interp = new ParserInterpreter(grammarFileName, vocabulary, ruleNames ?? Array.Empty<string>(), atn, input);

// The ArgumentNullException message names the null parameter; pre-validate each argument
Args.NotNull(nameof(atn), atn);
Args.NotNull(nameof(input), input);

try { CallRuntimeApi(a, b, c); } catch (ArgumentNullException ane) { LogMissingDependency(ane.ParamName); throw; }

When it happens

Trigger: Passing null to any runtime API guarded by Args.NotNull — typical call sites include setting a null ATN/deserializer on a simulator, constructing ParserInterpreter with null rule names or ATN, and recognizer Reset/Process calls with null streams. The parameter name in the exception message tells you which argument was null.

Common situations: DI containers resolving an optional dependency (vocabulary, error listener) to null; optional parameters defaulted to null then forwarded into runtime APIs; partial construction where a field is still null when the runtime API is invoked.

Related errors

• target cannot be null.
• tokenSource cannot be null
• nextToken requires a non-null input stream.
• tokens cannot be null
• tree cannot be null

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