dotnet/machinelearning · error · ArgumentNullException

throw new ArgumentNullException(nameof(vocabFile));

Error message

throw new ArgumentNullException(nameof(vocabFile));

What it means

BpeOptions requires a vocabulary file path to construct the BPE tokenizer model. The constructor throws ArgumentNullException immediately when the vocabFile argument is null, before any file I/O happens. This is a fail-fast guard so callers learn about the missing argument at construction time rather than deeper in tokenization.

Source

Thrown at src/Microsoft.ML.Tokenizers/Model/BpeOptions.cs:41

        {
            if (vocabulary == null)
            {
                throw new ArgumentNullException(nameof(vocabulary));
            }

            Vocabulary = vocabulary;
        }

        /// <summary>
        /// Initializes a new instance of the <see cref="BpeOptions"/> class.
        /// </summary>
        /// <param name="vocabFile">The JSON file path containing the dictionary of string keys and their ids.</param>
        /// <param name="mergesFile">The file path containing the tokens's pairs list.</param>
        public BpeOptions(string vocabFile, string? mergesFile = null)
        {
            if (vocabFile is null)
            {
                throw new ArgumentNullException(nameof(vocabFile));
            }

            if (!File.Exists(vocabFile))
            {
                throw new ArgumentException($"Could not find the vocabulary file '{vocabFile}'.");
            }

            using Stream vocabStream = File.OpenRead(vocabFile);
            Dictionary<string, int>? dictionary = JsonSerializer.Deserialize<Dictionary<string, int>>(vocabStream);

            if (dictionary is null)
            {
                throw new InvalidOperationException($"The content of the vocabulary file '{vocabFile}' is not valid.");
            }

            Vocabulary = dictionary;

            if (mergesFile is not null)

View on GitHub (pinned to 7b76e69cf9)

Solutions

1. Pass a valid, non-null vocabulary file path as the first constructor argument.
2. Resolve the path from configuration or a known model directory and assert it is not null before constructing BpeOptions.
3. If the vocabulary is only available in memory, use the Stream-based BpeOptions overload instead.

Example fix

// before
var options = new BpeOptions(config["VocabPath"]!);
// after
string vocabPath = config["VocabPath"] ?? throw new InvalidOperationException("VocabPath not configured");
var options = new BpeOptions(vocabPath);

if (vocabPath is null || !File.Exists(vocabPath)) throw new ArgumentException("vocabPath must be a non-null path to an existing vocab.json");

if (vocabPath is string p && p.Length > 0) { /* safe to construct */ }

try { var options = new BpeOptions(vocabPath); } catch (ArgumentNullException ex) { logger.LogError(ex, "Vocab path was null"); }

When it happens

Trigger: Calling new BpeOptions(null) or new BpeOptions(vocabFile: null, mergesFile: "merges.txt"); passing a path variable that was never initialized or defaulted to null from configuration.

Common situations: Config binding produced a null path because the settings key was missing; a caller passed null intentionally expecting the parameter to be optional (only mergesFile is optional); refactoring changed a non-null default to null.

Related errors

• throw new ArgumentNullException(nameof(vocabStream));
• throw new ArgumentNullException(nameof(vocabFilePath));
• throw new ArgumentNullException(nameof(vocabStream));
• throw new ArgumentNullException(nameof(vocabulary));
• throw new ArgumentNullException(nameof(vocabularyPath));

AI-assisted analysis of dotnet/machinelearning@7b76e69cf9 (2026-09-11). Data as JSON: /api/errors/cd7c8923799fe0cf. Report an issue: GitHub.