Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: explain failed and recurring llama.cpp runtime repairs (#12106)
UmranProsca5e2fddd671
diff --git a/studio/frontend/src/hooks/backend-preflight-message.ts b/studio/frontend/src/hooks/backend-preflight-message.tsindex b219578c0a4..7d9aed9bd51 100644--- a/studio/frontend/src/hooks/backend-preflight-message.ts+++ b/studio/frontend/src/hooks/backend-preflight-message.ts@@ -26,6 +26,24 @@ export const LLAMA_RUNTIME_REASONS = ["llama_runtime_incomplete",];+export function isLlamaRuntimeReason(reason: string | null): boolean {+ return LLAMA_RUNTIME_REASONS.includes((reason ?? "").split(":", 1)[0]);+}++function llamaRuntimeFolder(): string {+ return typeof navigator !== "undefined" && /Win/i.test(navigator.platform ?? "")+ ? "%USERPROFILE%\\.unsloth\\llama.cpp"+ : "~/.unsloth/llama.cpp";+}++export function runtimeRepairFailureMessage(error: string): string {+ return `Unsloth could not repair its llama.cpp runtime. Antivirus may be blocking the download or removing files as they are installed. Allow the runtime folder, usually ${llamaRuntimeFolder()}, in your antivirus, or check your connection, then retry. Repair error: ${error}`;+}++export function runtimeRepairRecurrenceMessage(): string {+ return `Unsloth's llama.cpp runtime is missing files again soon after a repair. Antivirus may be removing them. Allow the runtime folder, usually ${llamaRuntimeFolder()}, in your antivirus, then press Retry to reinstall it.`;+}+export function preflightStaleMessage(disposition: string,reason: string | null,@@ -52,17 +70,13 @@ export function preflightStaleMessage(// The install is current, some of its files are gone, so "too old" sends people// to an update that reports they are up to date. Name the usual cause: a// reinstall into the same quarantine needs an exclusion, not a retry.- if (LLAMA_RUNTIME_REASONS.includes(kind)) {+ if (isLlamaRuntimeReason(kind)) {// Named, because "allow the folder" leaves the user to find out which folder,// and an exclusion is the one step that stops this recurring. The default// root, since UNSLOTH_LLAMA_CPP_PATH can move it and preflight does not send// the path: hedged with "usually" rather than asserted. Windows spelling on// Windows, the same platform test the roaming-profile hint above uses.- const folder =- typeof navigator !== "undefined" && /Win/i.test(navigator.platform ?? "")- ? "%USERPROFILE%\\.unsloth\\llama.cpp"- : "~/.unsloth/llama.cpp";- return `Unsloth's llama.cpp runtime is missing files, which usually means security software quarantined them. Run \`unsloth studio update\` to reinstall it, and allow the folder it installs into, usually ${folder}, in your antivirus if it happens again.`;+ return `Unsloth's llama.cpp runtime is missing files, which usually means security software quarantined them. Run \`unsloth studio update\` to reinstall it, and allow the folder it installs into, usually ${llamaRuntimeFolder()}, in your antivirus if it happens again.`;}if (disposition === "owned_stale") {return "Desktop-owned Unsloth backend is too old for this desktop app. Run `unsloth studio update`, then restart Unsloth.";diff --git a/studio/frontend/src/hooks/runtime-repair-history.ts b/studio/frontend/src/hooks/runtime-repair-history.tsnew file mode 100644index 00000000000..a17f0b443d0--- /dev/null+++ b/studio/frontend/src/hooks/runtime-repair-history.ts@@ -0,0 +1,49 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import { isLlamaRuntimeReason } from "./backend-preflight-message.ts";++export const RUNTIME_REPAIR_KEY = "unsloth-llama-runtime-repair";+const RECURRENCE_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;++export function recordRuntimeRepair(+ reason: string | null,+ now = Date.now(),+): void {+ if (!isLlamaRuntimeReason(reason)) return;+ try {+ localStorage.setItem(+ RUNTIME_REPAIR_KEY,+ JSON.stringify({ reason, repairedAt: now }),+ );+ } catch {+ // Storage can be disabled; a failed write must not fail the repair.+ }+}++export function wasRuntimeRepairedRecently(+ reason: string | null,+ now = Date.now(),+): boolean {+ if (!isLlamaRuntimeReason(reason)) return false;+ try {+ const raw = localStorage.getItem(RUNTIME_REPAIR_KEY);+ if (!raw) return false;+ const record: unknown = JSON.parse(raw);+ if (!record || typeof record !== "object") return false;+ const { reason: previousReason, repairedAt } = record as Record<+ string,+ unknown+ >;+ return (+ typeof previousReason === "string" &&+ isLlamaRuntimeReason(previousReason) &&+ typeof repairedAt === "number" &&+ Number.isFinite(repairedAt) &&+ now >= repairedAt &&+ now - repairedAt <= RECURRENCE_WINDOW_MS+ );+ } catch {+ return false;+ }+}diff --git a/studio/frontend/src/hooks/use-tauri-backend.ts b/studio/frontend/src/hooks/use-tauri-backend.tsindex 1ec8849932a..afd4a142017 100644--- a/studio/frontend/src/hooks/use-tauri-backend.ts+++ b/studio/frontend/src/hooks/use-tauri-backend.ts@@ -13,7 +13,14 @@ import {MANAGED_ENVIRONMENT_BUSY,MANAGED_ENVIRONMENT_UPDATING,preflightStaleMessage,+ runtimeRepairFailureMessage,+ runtimeRepairRecurrenceMessage,+ isLlamaRuntimeReason,} from "@/hooks/backend-preflight-message";+import {+ recordRuntimeRepair,+ wasRuntimeRepairedRecently,+} from "@/hooks/runtime-repair-history";import {copySupportDiagnostics,type CopySupportDiagnosticsResult,@@ -178,6 +185,10 @@ export function useTauriBackend() {// Whether the repair in flight was asked to skip straight to the installer. Read back by// approveElevation, which restarts the repair after the system packages land.const forcedRepairRef = useRef(false);+ const repairReasonRef = useRef<string | null>(null);+ // Set by Retry: the next preflight may repair a runtime that was repaired recently. Only+ // the automatic launch-time repair is held back; a click is the user asking for it.+ const allowHeldRuntimeRepairRef = useRef(false);// One preflight and one repair at a time. Retry runs the preflight, a stale verdict starts a// repair, and five clicks two seconds apart used to fan out into five of each: the Rust side// saw them as five repairs racing for one installer.@@ -310,6 +321,8 @@ export function useTauriBackend() {}if (preflightInFlightRef.current) return;preflightInFlightRef.current = true;+ const allowHeldRuntimeRepair = allowHeldRuntimeRepairRef.current;+ allowHeldRuntimeRepairRef.current = false;// Released below and again in the finally; by then a later call may hold the flag, and// clearing it unowned would let a third preflight through.let ownsPreflight = true;@@ -365,11 +378,17 @@ export function useTauriBackend() {preflight.reason === MANAGED_ENVIRONMENT_BUSY ||preflight.reason === MANAGED_ENVIRONMENT_UPDATING) {+ // Still the same Retry: the check the wait ends in may use it.+ allowHeldRuntimeRepairRef.current = allowHeldRuntimeRepair;waitForManagedEnvironment(preflight.reason === MANAGED_ENVIRONMENT_BUSY);return;}if (preflight.can_auto_repair) {- await startRepair();+ if (!allowHeldRuntimeRepair && wasRuntimeRepairedRecently(preflight.reason)) {+ setBackendError(runtimeRepairRecurrenceMessage());+ } else {+ await startRepair({ preflightReason: preflight.reason });+ }} else {setBackendError(preflightStaleMessage(preflight.disposition, preflight.reason),@@ -446,7 +465,7 @@ export function useTauriBackend() {// automatic callers leave it off, because an out-of-date venv is the common case. Settings'// manual repair turns it on: an update reuses the environment it finds, so a venv whose// PyTorch was replaced by a CPU-only wheel comes back from one still CPU-only.- async function startRepair(options?: { forceInstaller?: boolean }) {+ async function startRepair(options?: { forceInstaller?: boolean; preflightReason?: string | null }) {if (repairInFlightRef.current) return;repairInFlightRef.current = true;// Same ownership rule as the preflight flag, handed to runRepair so it can release as soon@@ -465,12 +484,13 @@ export function useTauriBackend() {}async function runRepair(- options?: { forceInstaller?: boolean },+ options?: { forceInstaller?: boolean; preflightReason?: string | null },releaseRepair: () => void = () => {},) {const forceInstaller = options?.forceInstaller ?? false;// Survives the elevation round trip: approveElevation resumes by calling this again.forcedRepairRef.current = forceInstaller;+ repairReasonRef.current = options?.preflightReason ?? null;elevationResumeRef.current = null;setCurrentStepIndex(-1);setProgressDetail(null);@@ -486,18 +506,22 @@ export function useTauriBackend() {const { invoke } = await import("@tauri-apps/api/core");try {await invoke("start_managed_repair", { forceInstaller });+ recordRuntimeRepair(repairReasonRef.current);// The repair ends here; what follows is an ordinary start, and holding the flag across it// swallows the Retry that server-start-timeout offers.releaseRepair();-- setBackendStatus("starting");- elevationResumeRef.current = null;- await startManagedServer();} catch (e) {const msg = String(e);if (msg.includes("NEEDS_ELEVATION")) return;- setBackendError(msg, "repair-error");+ setBackendError(+ isLlamaRuntimeReason(repairReasonRef.current) ? runtimeRepairFailureMessage(msg) : msg,+ "repair-error",+ );+ return;}+ setBackendStatus("starting");+ elevationResumeRef.current = null;+ await startManagedServer();}async function startServer() {@@ -596,6 +620,7 @@ export function useTauriBackend() {void startRepair({ forceInstaller: true });return;}+ allowHeldRuntimeRepairRef.current = true;checkInstallAndStart();}, []);@@ -630,7 +655,10 @@ export function useTauriBackend() {setProgressDetail(null);elevationResumeRef.current = null;if (resume === "repair") {- await startRepair({ forceInstaller: forcedRepairRef.current });+ await startRepair({+ forceInstaller: forcedRepairRef.current,+ preflightReason: repairReasonRef.current,+ });} else {await startInstall();}@@ -748,7 +776,12 @@ export function useTauriBackend() {register<string>("repair-failed", (e) => {if (statusRef.current !== "repairing") return;- setBackendError(e.payload, "repair-error");+ setBackendError(+ isLlamaRuntimeReason(repairReasonRef.current)+ ? runtimeRepairFailureMessage(e.payload)+ : e.payload,+ "repair-error",+ );});register<number>("server-port", (e) => {diff --git a/studio/frontend/src/lib/account-transition.ts b/studio/frontend/src/lib/account-transition.tsindex c38205a05f5..a73c96ec5cc 100644--- a/studio/frontend/src/lib/account-transition.ts+++ b/studio/frontend/src/lib/account-transition.ts@@ -1,6 +1,7 @@// SPDX-License-Identifier: AGPL-3.0-only// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0+import { RUNTIME_REPAIR_KEY } from "../hooks/runtime-repair-history.ts";import { USER_STOPPED_KEY } from "../hooks/server-stop-intent.ts";export const BROWSER_ACCOUNT_KEY = "unsloth.browser-account.v1";@@ -207,6 +208,8 @@ export async function transitionBrowserAccount(!key ||key === BROWSER_ACCOUNT_KEY ||ACCOUNT_CHROME_KEYS.has(key) ||+ // About this machine's install, not the account signed in to it.+ key === RUNTIME_REPAIR_KEY ||ACCOUNT_CHROME_PREFIXES.some((prefix) => key.startsWith(prefix)))continue;diff --git a/studio/frontend/tests/account-transition.test.ts b/studio/frontend/tests/account-transition.test.tsindex 38ade3010ce..398a27d191f 100644--- a/studio/frontend/tests/account-transition.test.ts+++ b/studio/frontend/tests/account-transition.test.ts@@ -16,6 +16,7 @@ import {resetFullAccessForMultiUser,transitionBrowserAccount,} from "../src/lib/account-transition.ts";+import { RUNTIME_REPAIR_KEY } from "../src/hooks/runtime-repair-history.ts";function browserWith(values: Record<string, string> = {},@@ -171,6 +172,13 @@ test("switch removes every content prefix and preserves only listed chrome and uassert.deepEqual(b.replaced, ["/change-password"]);});+test("a switch keeps the machine's llama.cpp runtime repair record", async () => {+ const b = browserWith({ [RUNTIME_REPAIR_KEY]: "repaired", unsloth_auth_token: "owner" });+ assert.equal(await transitionBrowserAccount("alice", "/chat", () => {}, b.browser), true);+ assert.equal(b.data.get(RUNTIME_REPAIR_KEY), "repaired");+ assert.equal(b.data.has("unsloth_auth_token"), false);+});+test("a first managed login clears legacy owner data even without a marker", async () => {const b = browserWith({ "unsloth-old-content": "owner" });assert.equal(diff --git a/studio/frontend/tests/backend-preflight-message.test.ts b/studio/frontend/tests/backend-preflight-message.test.tsindex f28b2fefa8d..8290ab8c45b 100644--- a/studio/frontend/tests/backend-preflight-message.test.ts+++ b/studio/frontend/tests/backend-preflight-message.test.ts@@ -14,6 +14,8 @@ import {WORKING_DIRECTORY_UNAVAILABLE,PATH_SETTING_UNRESOLVABLE,preflightStaleMessage,+ runtimeRepairFailureMessage,+ runtimeRepairRecurrenceMessage,} from "../src/hooks/backend-preflight-message.ts";const UNREACHABLE_PROFILE = /cannot reach your user folder/;@@ -120,6 +122,21 @@ test("a quarantined llama.cpp runtime is not reported as an outdated install", (}});+test("a failed repair and recurring damage show antivirus advice with the runtime folder", () => {+ const failure = runtimeRepairFailureMessage("download blocked");+ assert.match(failure, /Antivirus may be blocking the download/);+ assert.match(failure, /or check your connection/);+ assert.match(failure, /Repair error: download blocked/);+ assert.match(failure, /\.unsloth[\\/]llama\.cpp/);++ const recurring = runtimeRepairRecurrenceMessage();+ assert.match(recurring, /missing files again soon after a repair/);+ assert.match(recurring, /antivirus/);+ assert.match(recurring, /press Retry to reinstall it/);+ assert.doesNotMatch(recurring, /unsloth studio update/);+ assert.match(recurring, /\.unsloth[\\/]llama\.cpp/);+});+test("the folder to exclude is spelled the way the platform spells it", () => {// The user pastes this into an antivirus exclusion list, so a POSIX path on// Windows is not advice. Same platform test as the roaming-profile hint.diff --git a/studio/frontend/tests/forced-repair-retry.test.ts b/studio/frontend/tests/forced-repair-retry.test.tsindex 463600cd093..0af814cfacd 100644--- a/studio/frontend/tests/forced-repair-retry.test.ts+++ b/studio/frontend/tests/forced-repair-retry.test.ts@@ -31,16 +31,23 @@ const body = lift("the retry callback",);-type Run = { repairs: boolean[]; preflights: number; forcedAfter: boolean };+type Run = {+ repairs: boolean[];+ preflights: number;+ forcedAfter: boolean;+ heldRepairAllowed: boolean;+};function runRetry(status: string, forced: boolean): Run {const repairs: boolean[] = [];const forcedRepairRef = { current: forced };+ const allowHeldRuntimeRepairRef = { current: false };let preflights = 0;const noop = () => {};const scope = {statusRef: { current: status },forcedRepairRef,+ allowHeldRuntimeRepairRef,startRepair: (options?: { forceInstaller?: boolean }) => {// The real one records the flag first; the fake mirrors that so the test can see// whether it survived the state reset that now runs ahead of the call.@@ -73,7 +80,12 @@ function runRetry(status: string, forced: boolean): Run {...keys,`${body.replace(/^const retry = /, "return ")}`.replace(/;\s*$/, ";"),)(...keys.map((key) => (scope as Record<string, unknown>)[key]))();- return { repairs, preflights, forcedAfter: forcedRepairRef.current };+ return {+ repairs,+ preflights,+ forcedAfter: forcedRepairRef.current,+ heldRepairAllowed: allowHeldRuntimeRepairRef.current,+ };}test("retry after a forced repair re-runs the forced repair", () => {@@ -105,3 +117,15 @@ test("retry from any other failure is untouched", () => {);}});++test("retry lets its preflight repair a recently repaired runtime; a forced resume does not need to", () => {+ // The recurrence hold is for the silent launch-time repair. A click still goes through+ // the preflight, which is what catches a busy, external or already fixed install.+ for (const status of ["error", "repair-error"]) {+ const run = runRetry(status, false);+ assert.equal(run.preflights, 1, `${status}: the retry still runs the preflight`);+ assert.deepEqual(run.repairs, [], `${status}: no repair without the preflight`);+ assert.equal(run.heldRepairAllowed, true, `${status}: the hold is lifted for it`);+ }+ assert.equal(runRetry("repair-error", true).heldRepairAllowed, false);+});diff --git a/studio/frontend/tests/managed-environment-wait.test.ts b/studio/frontend/tests/managed-environment-wait.test.tsindex c38bad2fd85..4ec12c95a24 100644--- a/studio/frontend/tests/managed-environment-wait.test.ts+++ b/studio/frontend/tests/managed-environment-wait.test.ts@@ -62,7 +62,11 @@ const BUSY: Preflight = {port: null,};-function harness(preflight: Preflight, authFailure: string | null = null) {+function harness(+ preflight: Preflight,+ authFailure: string | null = null,+ runtimeRepairedRecently = false,+) {const errors: string[] = [];const statuses: string[] = [];const messages: string[] = [];@@ -71,6 +75,7 @@ function harness(preflight: Preflight, authFailure: string | null = null) {let armed: (() => void) | null = null;let armedCount = 0;const environmentWaitPollsRef = { current: 0 };+ const allowHeldRuntimeRepairRef = { current: false };const noop = () => {};const scope: Record<string, unknown> = {@@ -126,6 +131,9 @@ function harness(preflight: Preflight, authFailure: string | null = null) {return Promise.resolve();},preflightStaleMessage: (_d: string, reason: string | null) => `stale:${reason}`,+ allowHeldRuntimeRepairRef,+ wasRuntimeRepairedRecently: () => runtimeRepairedRecently,+ runtimeRepairRecurrenceMessage: () => "runtime damaged again",externalConflictMessage: () => "conflict",};@@ -162,6 +170,10 @@ ${checkBodyreturn armed !== null;},polls: () => environmentWaitPollsRef.current,+ allowHeldRepair() {+ allowHeldRuntimeRepairRef.current = true;+ },+ heldRepairAllowed: () => allowHeldRuntimeRepairRef.current,async fireWait() {const next = armed;assert.ok(next, "no wait was armed");@@ -211,6 +223,40 @@ test("a stale install that is not busy still repairs", async () => {assert.equal(run.waiting, false);});+test("a runtime damaged again soon after a repair explains instead of repairing", async () => {+ const run = harness({ ...BUSY, reason: "llama_runtime_binaries_missing" }, null, true);+ await run.check();++ assert.equal(run.repairs, 0);+ assert.equal(run.errors.at(-1), "runtime damaged again");+});++test("after Retry, the preflight repairs a recently repaired runtime, once", async () => {+ const run = harness({ ...BUSY, reason: "llama_runtime_binaries_missing" }, null, true);+ run.allowHeldRepair();+ await run.check();+ assert.equal(run.repairs, 1, "the click asked for the repair the message offered");+ assert.equal(run.heldRepairAllowed(), false, "consumed by that preflight");++ await run.check();+ assert.equal(run.repairs, 1, "the next automatic preflight holds it back again");+ assert.equal(run.errors.at(-1), "runtime damaged again");+});++test("a Retry that lands on a busy environment still repairs once the wait ends", async () => {+ const preflight = { ...BUSY };+ const run = harness(preflight, null, true);+ run.allowHeldRepair();+ await run.check();+ assert.equal(run.waiting, true);+ assert.equal(run.repairs, 0);++ preflight.reason = "llama_runtime_binaries_missing";+ await run.fireWait();+ assert.equal(run.repairs, 1, "the click carried through the wait");+ assert.equal(run.heldRepairAllowed(), false);+});+test("the wait is bounded, so a gate nobody releases still reaches Retry", async () => {const run = harness(BUSY);await run.check();diff --git a/studio/frontend/tests/repair-single-flight.test.ts b/studio/frontend/tests/repair-single-flight.test.tsindex de6ed653064..251b2ad3b50 100644--- a/studio/frontend/tests/repair-single-flight.test.ts+++ b/studio/frontend/tests/repair-single-flight.test.ts@@ -53,7 +53,7 @@ test("a preflight already in flight is not run again", () => {body.indexOf("await startManagedServer()") > release,"no long await may run while the flag is held",);- assert.ok(body.indexOf("await startRepair()") > release);+ assert.ok(body.indexOf("await startRepair({ preflightReason: preflight.reason })") > release);// Released twice, and by then a later call may hold the flag: an unowned clear would let a// third preflight through.assert.match(diff --git a/studio/frontend/tests/runtime-repair-history.test.ts b/studio/frontend/tests/runtime-repair-history.test.tsnew file mode 100644index 00000000000..01cd110f356--- /dev/null+++ b/studio/frontend/tests/runtime-repair-history.test.ts@@ -0,0 +1,49 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import assert from "node:assert/strict";+import test from "node:test";++import {+ recordRuntimeRepair,+ wasRuntimeRepairedRecently,+} from "../src/hooks/runtime-repair-history.ts";++test("a successful runtime repair is remembered across launches, then expires", () => {+ const values = new Map<string, string>();+ const original = globalThis.localStorage;+ Object.defineProperty(globalThis, "localStorage", {+ configurable: true,+ value: {+ getItem: (key: string) => values.get(key) ?? null,+ setItem: (key: string, value: string) => { values.set(key, value); },+ },+ });+ try {+ const now = 1_000_000_000;+ recordRuntimeRepair("backend_outdated", now);+ assert.equal(wasRuntimeRepairedRecently("llama_runtime_dir_missing", now), false);++ recordRuntimeRepair("llama_runtime_dir_missing", now);+ assert.equal(wasRuntimeRepairedRecently("llama_runtime_binaries_missing", now + 1000), true);+ assert.equal(wasRuntimeRepairedRecently("backend_outdated", now + 1000), false);+ assert.equal(wasRuntimeRepairedRecently("llama_runtime_dir_missing", now - 1), false);+ assert.equal(wasRuntimeRepairedRecently("llama_runtime_dir_missing", now + 8 * 86400_000), false);+ } finally {+ Object.defineProperty(globalThis, "localStorage", { configurable: true, value: original });+ }+});++test("blocked storage never prevents a runtime repair", () => {+ const original = globalThis.localStorage;+ Object.defineProperty(globalThis, "localStorage", {+ configurable: true,+ get: () => { throw new Error("storage blocked"); },+ });+ try {+ assert.doesNotThrow(() => recordRuntimeRepair("llama_runtime_incomplete"));+ assert.equal(wasRuntimeRepairedRecently("llama_runtime_incomplete"), false);+ } finally {+ Object.defineProperty(globalThis, "localStorage", { configurable: true, value: original });+ }+});