SubtitleEdit/subtitleedit · critical · InvalidOperationException

llama-server exited during startup (code {process.ExitCode})

Error message

llama-server exited during startup (code {process.ExitCode}). Output: {tail}

What it means

InvalidOperationException thrown inside the startup-health loop when the llama-server process exits before its /health endpoint answers. The message embeds the process exit code and the tail of captured server output, so the underlying crash reason is in the exception text. Reaching it means the binary launched but crashed during model load or context init.

Source

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

            process.BeginOutputReadLine();

            _serverProcess = process;
            _serverPort = port;
            _serverModelPath = modelPath;
            _serverContextSize = contextSize;
            HookProcessExitOnce();

            var deadline = DateTime.UtcNow.AddMinutes(5);
            while (DateTime.UtcNow < deadline)
            {
                cancellationToken.ThrowIfCancellationRequested();
                if (process.HasExited)
                {
                    var tail = SnapshotServerLog();
                    _serverProcess = null;
                    _serverPort = 0;
                    _serverModelPath = null;
                    throw new InvalidOperationException(
                        $"llama-server exited during startup (code {process.ExitCode}). Output: {tail}");
                }

                if (await ProbeHealthAsync(port, TimeSpan.FromSeconds(2), cancellationToken))
                {
                    Configuration.Settings.Tools.LlamaCppApiUrl = ApiUrl;
                    return;
                }

                await Task.Delay(TimeSpan.FromSeconds(1), cancellationToken);
            }

            var lastOutput = SnapshotServerLog();
            StopServerInternal();
            throw new TimeoutException(
                $"llama-server did not report healthy within 5 minutes. Last output: {lastOutput}");
        }
        finally

View on GitHub (pinned to 17a9f07487)

Solutions

Read the embedded tail in the exception — llama-server prints the real error (CUDA error, 'failed to load model', gguf parse error) to stderr.
If CUDA is missing/broken, install matching CUDA + cuDNN or force CPU mode by removing any --n-gpu-layers flag in the launch args.
For VRAM exhaustion, pick a smaller quant or pass fewer GPU layers; verify free memory with nvidia-smi before starting.
Re-verify the .gguf integrity (file size vs HuggingFace) and that --chat-template matches the model family.
Reproduce the launch with the exact FormatLaunchCommand output in a terminal to see live stderr.

Example fix

// before
throw new InvalidOperationException(
    $"llama-server exited during startup (code {process.ExitCode}). Output: {tail}");

// after — keep the tail, but also stash last exit code for callers
teardown(process);
throw new InvalidOperationException(
    $"llama-server exited during startup (code {process.ExitCode}). " +
    $"Rerun manually: {FormatLaunchCommand(exe, psi.ArgumentList)}. Output: {tail}");

Defensive patterns

Strategy: try-catch

Validate before calling

public static void PreFlight(string exe, string modelPath)
{
    if (!File.Exists(exe) || !File.Exists(modelPath)) throw new InvalidOperationException("Missing llama-server or model.");
    if (OperatingSystem.IsLinux() && !HasCudaLibs()) LogWarning("CUDA libs missing; llama-server may crash on GPU init.");
}

Type guard

null

Try / catch

try { await StartServerAsync(...); }
catch (InvalidOperationException ex) when (ex.Message.Contains("exited during startup"))
{ SeLogger.Error(ex, "llama-server crashed at startup; rerun command manually."); throw; }

Prevention

Always log the full embedded tail when this fires — the real cause is in there.
Run the formatted launch command in a shell once to confirm it boots standalone.
Match CUDA/cuDNN versions to the llama.cpp build before invoking.

When it happens

Trigger: llama-server exits non-zero within the 5-minute startup window. Typical causes: missing CUDA/cuDNN shared libraries, out-of-memory (GPU VRAM or system RAM), an unreadable or unsupported .gguf, mismatched --chat-template/--no-jinja flags, or an invalid port/argument.

Common situations: First run on a machine without matching CUDA toolkit; model larger than available VRAM; mmproj version mismatched to the model; recent llama.cpp upgrade changed required flags.

Related errors

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