SubtitleEdit/subtitleedit · error · FileNotFoundException

llama.cpp vision projector not found - please download the m

Error message

llama.cpp vision projector not found - please download the model first.

What it means

Thrown when a multimodal model declares MmprojFileName but the resolved mmproj file (the vision projector, typically mmproj-*.gguf) is absent on disk. Reaching here means the text model file passed its check; only the optional vision projector is missing.

Source

Thrown at src/libuilogic/LlamaCpp/LlamaCppServerManager.cs:515

            var exe = GetExecutable();
            if (!File.Exists(exe))
            {
                throw new FileNotFoundException("llama-server executable not found - please download llama.cpp first.", exe);
            }

            if (!File.Exists(modelPath))
            {
                throw new FileNotFoundException("llama.cpp model not found - please download a model first.", modelPath);
            }

            string? mmprojPath = null;
            if (model.MmprojFileName != null)
            {
                mmprojPath = GetModelPath(model.MmprojFileName);
                if (!File.Exists(mmprojPath))
                {
                    throw new FileNotFoundException("llama.cpp vision projector not found - please download the model first.", mmprojPath);
                }
            }

            var port = FindFreeLoopbackPort();
            var psi = new ProcessStartInfo
            {
                WorkingDirectory = Path.GetDirectoryName(exe) ?? GetAndCreateFolder(),
                FileName = exe,
                UseShellExecute = false,
                CreateNoWindow = true,
                RedirectStandardError = true,
                RedirectStandardOutput = true,
            };
            psi.ArgumentList.Add("-m");
            psi.ArgumentList.Add(modelPath);
            if (mmprojPath != null)
            {
                psi.ArgumentList.Add("--mmproj");

View on GitHub (pinned to 17a9f07487)

Solutions

Download the matching mmproj-*.gguf from the same HuggingFace repo as the model and place it in the same Models folder.
If you do not need vision OCR, set MmprojFileName to null for this model so the projector check is skipped.
Confirm the exact mmproj filename matches what GetModelPath expects (case-sensitive on Linux).

Example fix

// before
if (!File.Exists(mmprojPath))
    throw new FileNotFoundException("llama.cpp vision projector not found - please download the model first.", mmprojPath);

// after
if (model.MmprojFileName != null)
{
    mmprojPath = GetModelPath(model.MmprojFileName);
    if (!File.Exists(mmprojPath))
        LogAction?.Invoke($"Vision projector missing at {mmprojPath}; vision OCR disabled.");
}

Defensive patterns

Strategy: validation

Validate before calling

if (model.MmprojFileName != null)
{
    var mmproj = GetModelPath(model.MmprojFileName);
    if (!File.Exists(mmproj))
        return Result.Fail($"Vision projector '{mmproj}' missing; vision OCR will be unavailable.");
}

Type guard

null

Try / catch

null

Prevention

When registering a multimodal model, require both the .gguf and the mmproj-*.gguf at config time.
Make the mmproj optional and degrade gracefully (text-only) instead of throwing if vision OCR is not needed.

When it happens

Trigger: A LlamaCppModel with non-null MmprojFileName where GetModelPath(model.MmprojFileName) returns a path that does not exist; user downloaded the LLM weights but not the matching mmproj sidecar.

Common situations: Pulling a multimodal model (e.g. Llama 3.2 Vision, Qwen2-VL) and forgetting the mmproj.gguf; the projector ships as a separate file on HuggingFace and was skipped.

Related errors

AI-assisted analysis of SubtitleEdit/subtitleedit@17a9f07487 (2026-08-13). Data as JSON: /api/errors/bacf3a17c067a759. Report an issue: GitHub.