dotnet/machinelearning · error · ArgumentException

Could not find the merges file

Error message

Could not find the merges file '{mergesFile}'.

What it means

When a mergesFile path is supplied (it is optional), BpeOptions verifies it exists and throws ArgumentException if not. The merges file contains the BPE token-pair merge rules and is required for correct BPE encoding, so a supplied-but-missing file is rejected immediately.

Solutions

1. Verify merges.txt exists at the exact path with File.Exists before constructing BpeOptions.
2. Download both vocab.json and merges.txt from the same model release so they are consistent.
3. Use an absolute or AppContext.BaseDirectory-relative path for the merges file.
4. If you truly do not need merges, pass null (the default) rather than a path to a missing file.

Example fix

// before
var options = new BpeOptions(vocabPath, "merges.txt");
// after
string mergesPath = Path.Combine(AppContext.BaseDirectory, "models", "merges.txt");
if (!File.Exists(mergesPath)) throw new FileNotFoundException("BPE merges file missing", mergesPath);
var options = new BpeOptions(vocabPath, mergesPath);

if (!File.Exists(mergesPath)) throw new FileNotFoundException("BPE merges file not found", mergesPath);

try { var options = new BpeOptions(vocabPath, mergesPath); } catch (ArgumentException ex) { logger.LogError(ex, "Merges file missing at {Path}", mergesPath); }

When it happens

Trigger: new BpeOptions("vocab.json", "merges.txt") where merges.txt is missing; passing a merges path from config where the file was never deployed; confusing the merges file name (some models ship merges.txt, others merges-model.txt).

Common situations: Only the vocab was downloaded from the model repo but the merges file was skipped; wrong relative path when app runs from a different working directory; renaming of asset files during deployment.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Could not find the vocabulary file
• argument should not be null.
• Cannot read the file Merge file.
• Cannot read the file Merge file.
• Failed to read the vocabulary file.

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

Appendix: source

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

            {
                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)
            {
                if (!File.Exists(mergesFile))
                {
                    throw new ArgumentException($"Could not find the merges file '{mergesFile}'.");
                }

                using Stream mergesStream = File.OpenRead(mergesFile);
                using StreamReader reader = new(mergesStream);

                List<string> merges = new();

                int lineNumber = 0;
                string? line;

                while ((line = reader.ReadLine()) is not null)
                {
                    lineNumber++;
                    if (line.StartsWith("#version", StringComparison.Ordinal) || line.Length == 0)
                    {
                        continue;
                    }

View on GitHub (pinned to 7b76e69cf9)