SubtitleEdit/subtitleedit · error · InvalidOperationException

llama.cpp returned {(int)resp.StatusCode}: {json}

Error message

llama.cpp returned {(int)resp.StatusCode}: {json}

What it means

Thrown by the llama.cpp OCR engine when the HTTP POST to the llama-server completion/chat endpoint returns a non-success HTTP status code. The response status code and the raw JSON body are embedded in the message. This is a runtime communication failure with an already-resolved llama-server instance — the server is reachable but rejected or failed the request.

Source

Thrown at src/seconv/Core/LlamaCppOcrEngine.cs:118

        using var image = SKImage.FromBitmap(padded);
        using var data = image.Encode(SKEncodedImageFormat.Png, 90);
        var base64 = Convert.ToBase64String(data.ToArray());

        var prompt = PromptTemplate.Replace("{language}", _language);
        var body = "{ \"model\": \"" + Escape(_modelName) + "\", \"temperature\": 0, \"messages\": [ { \"role\": \"user\", \"content\": [ " +
                   "{ \"type\": \"text\", \"text\": \"" + Escape(prompt) + "\" }, " +
                   "{ \"type\": \"image_url\", \"image_url\": { \"url\": \"data:image/png;base64," + base64 + "\" } } " +
                   "] } ] }";

        using var content = new StringContent(body, Encoding.UTF8);
        content.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json");

        var resp = _httpClient.PostAsync(url, content).GetAwaiter().GetResult();
        var bodyBytes = resp.Content.ReadAsByteArrayAsync().GetAwaiter().GetResult();
        var json = Encoding.UTF8.GetString(bodyBytes).Trim();
        if (!resp.IsSuccessStatusCode)
        {
            throw new InvalidOperationException($"llama.cpp returned {(int)resp.StatusCode}: {json}");
        }

        var parser = new SeJsonParser();
        var contents = parser.GetAllTagsByNameAsStrings(json, "content");
        var text = string.Join(string.Empty, contents).Trim();
        text = text.Replace("\\n", Environment.NewLine).Replace("\\\"", "\"");
        return text.Trim();
    }

    /// <summary>
    /// Resolves <c>--ocr-model</c> to an installed model: a full <c>.gguf</c> path (needs its
    /// mmproj vision-projector sidecar next to it), a curated OCR model by file/display name,
    /// or - when omitted - the first installed curated OCR model.
    /// </summary>
    internal static LlamaCppModel ResolveOcrModel(string? requestedModel)
    {
        var curatedNames = string.Join(", ", LlamaCppServerManager.OcrModels.Select(m => m.FileName));

View on GitHub (pinned to 17a9f07487)

Solutions

1. Check the embedded status code: 404 = wrong endpoint URL, 400 = bad request body, 500/503 = model/server failure — inspect the JSON body in the message for the server's error detail.
2. Verify the model loads correctly by starting llama-server standalone and testing with curl against the same endpoint.
3. Ensure sufficient VRAM/RAM for the model — try a smaller model or reduce context size.
4. For OCR, confirm the model has vision capability (mmproj loaded) — a text-only model cannot process the image_url field.
5. Update llama.cpp and the model to compatible versions.

try { var text = ocrEngine.Recognize(imageBitmap); }
catch (InvalidOperationException ex) when (ex.Message.Contains("llama.cpp returned"))
{
    // Parse status code from message; inspect JSON body for server-side detail
    // Common fixes: check model loads, reduce context size, verify vision capability
}

When it happens

Trigger: The llama-server is running but returns an error: the model failed to load (500), the request payload is malformed (400), the server is overloaded or the model is too large for available VRAM/RAM (503/500), the endpoint path is wrong (404), or authentication is required.

Common situations: Model file is corrupt or unsupported by the llama.cpp build; insufficient GPU/CPU memory for the model; the server was started with a text-only model (no vision support) for an OCR request; a version mismatch between the llama-server API and the client's expected endpoint shape.

Related errors

• llama-server not found. Either: download llama.cpp in Subtit
• OCR model file not found: {name}
• No vision projector found next to {fullPath}. llama.cpp OCR
• OCR model '{name}' not found in {LlamaCppServerManager.GetAn
• No llama.cpp OCR model found in {LlamaCppServerManager.GetAn

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