Skip to content

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.

Improve model-load error guidance and shorten failure notifications (#16540)

Lee Jackson8f2ba4836e52
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 880fa8b1ca2..f879b187070 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -21262,6 +21262,32 @@ class LlamaCppBackend:
secrets,
)
+ # Projectors, drafters and shards fail this way too: never name the main GGUF.
+ if "data is not within the file bounds" in lowered:
+ return LlamaCppBackend._with_startup_diagnostics(
+ "A model file appears incomplete or damaged. Check that the download finished.",
+ output,
+ log_path,
+ secrets,
+ )
+
+ if "failed to open gguf file" in lowered:
+ return LlamaCppBackend._with_startup_diagnostics(
+ "Couldn't open a model file. Check it exists and Unsloth has permission to read it.",
+ output,
+ log_path,
+ secrets,
+ )
+
+ # GPU evidence on the allocation line itself: a host allocation failure keeps the fallback.
+ if LlamaCppBackend._is_gpu_memory_start_failure(scan_tail):
+ return LlamaCppBackend._with_startup_diagnostics(
+ "Couldn't allocate memory. Try lowering the context length or choosing a smaller model.",
+ output,
+ log_path,
+ secrets,
+ )
+
# Detect Ollama first so the arch branch keeps the Ollama hint.
gguf = gguf_path or ""
is_ollama = (
@@ -21350,8 +21376,9 @@ class LlamaCppBackend:
# Includes an arch the installed build predates.
return (
f"The installed llama.cpp does not recognise this GGUF's model "
- f"architecture ('{arch}'). The file is valid. If the model is newer "
- "than this llama.cpp build, updating llama.cpp may add support for it."
+ f"architecture ('{arch}'). Check the model card for its required runtime. "
+ "If the model is newer than this llama.cpp build, updating llama.cpp may "
+ "add support; a model requiring a custom runtime may still be incompatible."
)
# Other Ollama compat failures, only when the output shows a GGUF compat issue.
@@ -21373,11 +21400,11 @@ class LlamaCppBackend:
if missing_key:
return LlamaCppBackend._with_startup_diagnostics(
f"This GGUF is missing the metadata key '{_short(missing_key.group(1))}', "
- "which the installed llama.cpp requires to load it. The file was made "
- "for a different llama.cpp version of this model's format, usually an "
- "older or pre-release one; this is not a memory problem. Download an "
- "updated GGUF of this model, or update llama.cpp if the file is newer "
- "than this build.",
+ "which the installed llama.cpp requires to load it; this is not a memory problem. "
+ "This can happen with an incompatible conversion, incomplete metadata, or "
+ "an adapter selected as a full model. Check the model card for its required "
+ "runtime and whether it needs a base model. Use a compatible full or updated "
+ "GGUF, or update llama.cpp if the model requires a newer build.",
output,
log_path,
secrets,
diff --git a/studio/backend/tests/test_llama_cpp_start_failure_classification.py b/studio/backend/tests/test_llama_cpp_start_failure_classification.py
index 4415e6bc2f3..00d255d274e 100644
--- a/studio/backend/tests/test_llama_cpp_start_failure_classification.py
+++ b/studio/backend/tests/test_llama_cpp_start_failure_classification.py
@@ -243,7 +243,7 @@ class TestOllamaAndFallback:
assert "another quant" in msg
assert "GGUF file is valid" not in msg
- def test_truncated_gguf_keeps_the_generic_message(self):
+ def test_truncated_gguf_explains_how_to_check_the_download(self):
# What a cut-off download prints: the header parses, the data does not fit.
out = (
"llama_model_load: error loading model: tensor 'output.weight' data is not "
@@ -251,8 +251,9 @@ class TestOllamaAndFallback:
"llama_model_load_from_file_impl: failed to load model\n"
)
msg = _classify(out, "/models/m.gguf", "local/m", 1)
- assert "GGUF file is valid" in msg
- assert "cannot read this GGUF" not in msg
+ assert "appears incomplete or damaged" in msg
+ assert "Check that the download finished" in msg
+ assert "GPU memory" not in msg
def test_known_type_with_ragged_rows_keeps_the_generic_message(self):
# A type this build has, with a row length its blocks do not divide: a damaged file.
@@ -265,9 +266,9 @@ class TestOllamaAndFallback:
assert "GGUF file is valid" in msg
assert "cannot read this GGUF" not in msg
- def test_generic_oom_keeps_memory_message(self):
+ def test_gpu_oom_has_actionable_memory_guidance(self):
msg = _classify(_OOM_OUT, "/models/big.gguf", "local/big")
- assert "enough memory" in msg.lower()
+ assert "Couldn't allocate memory" in msg
assert "diffusion" not in msg.lower()
def test_empty_output_is_safe(self):
@@ -547,7 +548,7 @@ class TestMissingSharedLibrary:
def test_a_normal_failure_is_untouched(self):
msg = _classify(_OOM_OUT, "/models/big.gguf", "local/big", 1)
- assert "enough memory" in msg.lower()
+ assert "Couldn't allocate memory" in msg
assert "system library" not in msg
def test_a_named_arch_wins_over_exit_127(self):
@@ -821,7 +822,6 @@ class TestANonGgufFile:
class TestStartupDiagnostics:
_UNKNOWN_OUT = (
"build: 9415 (06d26dfd) with Apple clang version 17.0.0 for arm64-apple-darwin24.6.0\n"
- "ggml_metal_init: error: failed to allocate buffer\n"
"GGML_ASSERT(ctx->device != nil) failed"
)
@@ -849,7 +849,7 @@ class TestStartupDiagnostics:
assert "\x1b" not in msg
assert "done" in msg
- def test_no_output_and_no_log_keeps_the_old_message_exactly(self):
+ def test_no_output_and_no_log_keeps_the_original_message_exactly(self):
assert _classify("", "/models/x.gguf", "local/x", 1) == (
"llama-server failed to start. "
"Check that the GGUF file is valid and you have enough memory."
@@ -1685,7 +1685,7 @@ class TestRejectedArguments:
def test_an_ordinary_failure_is_untouched(self):
msg = _classify(_OOM_OUT, "/models/big.gguf", "local/big", 1)
- assert "enough memory" in msg.lower()
+ assert "Couldn't allocate memory" in msg
assert "argument" not in msg.lower()
def test_the_argument_scan_reads_only_the_tail(self):
@@ -1775,3 +1775,107 @@ class TestTensorSplitQuantizedKvUnsupported:
which is why it needs its own recording path rather than the #6415 one."""
assert not LlamaCppBackend._should_record_tensor_split_abort(1, self._OUT)
assert not LlamaCppBackend._is_tensor_split_assert(self._OUT)
+
+
+class TestActionableStartupFailures:
+ @pytest.mark.parametrize(
+ "output",
+ [
+ _OOM_OUT,
+ "ggml_backend_hip: hipMalloc failed: hipErrorOutOfMemory",
+ "ggml_vulkan: vk::Device::allocateMemory: ErrorOutOfDeviceMemory "
+ "VK_ERROR_OUT_OF_DEVICE_MEMORY",
+ "ggml_metal_init: error: failed to allocate buffer",
+ "ggml_cuda_host_malloc: failed to allocate pinned memory: out of memory",
+ ],
+ )
+ def test_gpu_allocation_failure_keeps_evidence_and_gives_next_steps(self, output):
+ msg = _classify(output, "/models/big.gguf", "local/big", 1, log_path = "/tmp/llama.log")
+ assert msg.startswith("Couldn't allocate memory.")
+ assert "lowering the context length" in msg
+ assert "choosing a smaller model" in msg
+ assert output in msg
+ assert "Full log: /tmp/llama.log" in msg
+
+ @pytest.mark.parametrize(
+ "output",
+ [
+ "ggml_backend_cpu: failed to allocate buffer",
+ "CUDA device 0 ready\nhost: failed to allocate buffer",
+ "CUDA device 0 ready\nunexpected runtime failure",
+ ],
+ )
+ def test_other_failures_do_not_claim_gpu_memory_exhaustion(self, output):
+ msg = _classify(output, "/models/m.gguf", "local/m", 1)
+ assert "GGUF file is valid" in msg
+ assert "Couldn't allocate memory" not in msg
+
+ @pytest.mark.parametrize("model_id", ["local/m", "ollama/m"])
+ def test_file_open_failure_names_checks_without_guessing_why(self, model_id):
+ output = (
+ "gguf_init_from_file: failed to open GGUF file '/models/vision.gguf'\n"
+ "llama_model_load_from_file_impl: failed to load model"
+ )
+ msg = _classify(output, "/models/main.gguf", model_id, 1, log_path = "/tmp/llama.log")
+ summary = msg.split("\n\n")[0]
+ assert "Couldn't open a model file" in summary
+ assert "Check it exists" in summary
+ assert "permission to read it" in summary
+ assert "main.gguf" not in summary
+ assert "vision.gguf" in msg
+ assert "Full log: /tmp/llama.log" in msg
+ assert "Couldn't allocate memory" not in msg
+
+ def test_corrupt_companion_does_not_blame_main_model(self):
+ output = (
+ "tensor 'vision.weight' data is not within the file bounds, "
+ "model is corrupted or incomplete"
+ )
+ msg = _classify(output, "/models/main.gguf", "local/m", 1, log_path = "/tmp/llama.log")
+ summary = msg.split("\n\n")[0]
+ assert "appears incomplete or damaged" in summary
+ assert "main.gguf" not in summary
+ assert output in msg
+ assert "Full log: /tmp/llama.log" in msg
+
+ def test_ollama_gpu_oom_is_not_misreported_as_format_incompatibility(self):
+ output = _OOM_OUT + "\nllama_model_load_from_file_impl: failed to load model"
+ msg = _classify(output, "/models/m.gguf", "ollama/m", 1)
+ assert msg.startswith("Couldn't allocate memory.")
+ assert "Some Ollama models" not in msg
+
+ def test_unknown_architecture_does_not_certify_the_file(self):
+ msg = _classify("unknown model architecture: 'custom_llm'", "/models/m.gguf", "local/m")
+ assert "The file is valid" not in msg
+ assert "model card" in msg
+ assert "custom runtime" in msg
+
+ def test_missing_metadata_does_not_assert_a_version_mismatch(self):
+ msg = _classify(
+ "key not found in model: deepseek41.context_length",
+ "/models/m.gguf",
+ "local/m",
+ )
+ assert "adapter selected as a full model" in msg
+ assert "required runtime" in msg
+ assert "The file was made" not in msg
+
+ @pytest.mark.parametrize(
+ "output",
+ [
+ _OOM_OUT,
+ "gguf_init_from_file: failed to open GGUF file",
+ "tensor data is not within the file bounds",
+ "unexpected runtime failure",
+ ],
+ )
+ def test_new_guidance_preserves_redacted_bounded_diagnostics(self, output):
+ secret = "hf_" + "a" * 34
+ output += "\n" + "x" * 5000 + "\n" + secret
+ msg = _classify(output, "/models/m.gguf", "local/m", 1, log_path = "/tmp/llama.log")
+ assert secret not in msg
+ assert "***" in msg
+ assert len(msg.split("\n\n")[0]) < 150
+ assert msg.count("llama-server output:") == 1
+ assert msg.count("Full log: /tmp/llama.log") == 1
+ assert len(msg) < 4000
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index 3943ef6a987..9f00c6ac22e 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -50,6 +50,7 @@ import {
offloadCountsFrom,
offloadWarning,
} from "../lib/partial-offload";
+import { loadFailureToastParts } from "../lib/load-failure-message";
import { isSettingsRouteAbsent } from "@/features/settings/api/settings-route-absent";
import {
failureLogPath,
@@ -3449,8 +3450,7 @@ export function useChatModelRuntime() {
if (!abortCtrl.signal.aborted) {
const message =
err instanceof Error ? err.message : "Failed to load model";
- const [summary, ...rest] = message.split("\n");
- const detail = rest.join("\n").trim();
+ const { summary, detail } = loadFailureToastParts(message);
const runnerLogPath = failureLogPath(message);
const logsAction = runnerLogPath
? viewLogsAction(
diff --git a/studio/frontend/src/features/chat/lib/load-failure-message.ts b/studio/frontend/src/features/chat/lib/load-failure-message.ts
new file mode 100644
index 00000000000..b3d8a6ca7b9
--- /dev/null
+++ b/studio/frontend/src/features/chat/lib/load-failure-message.ts
@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export function loadFailureToastParts(message: string): {
+ summary: string;
+ detail: string;
+} {
+ let visible = message;
+ for (const marker of ["\n\nllama-server output:", "\n\nFull log: "]) {
+ const at = visible.indexOf(marker);
+ if (at !== -1) {
+ visible = visible.slice(0, at);
+ }
+ }
+ const [summary, ...rest] = visible.trim().split("\n");
+ return { summary, detail: rest.join("\n").trim() };
+}
diff --git a/studio/frontend/tests/load-failure-message.test.ts b/studio/frontend/tests/load-failure-message.test.ts
new file mode 100644
index 00000000000..1d1f0b2e203
--- /dev/null
+++ b/studio/frontend/tests/load-failure-message.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 { loadFailureToastParts } from "../src/features/chat/lib/load-failure-message.ts";
+
+test("runtime output and log path stay out of the toast", () => {
+ const message =
+ "Couldn't allocate memory. Try lowering the context length.\n\nllama-server output:\ncudaMalloc failed: out of memory\n\nFull log: /tmp/llama.log";
+ assert.deepEqual(loadFailureToastParts(message), {
+ summary: "Couldn't allocate memory. Try lowering the context length.",
+ detail: "",
+ });
+ assert.ok(
+ message.includes("cudaMalloc failed"),
+ "the original error remains copyable",
+ );
+});
+
+test("a log path without output is also kept out of the toast", () => {
+ assert.deepEqual(
+ loadFailureToastParts("Couldn't start.\n\nFull log: /tmp/llama.log"),
+ {
+ summary: "Couldn't start.",
+ detail: "",
+ },
+ );
+});
+
+test("ordinary multiline guidance is preserved", () => {
+ assert.deepEqual(
+ loadFailureToastParts(
+ "Load refused.\nTry again after the current task finishes.",
+ ),
+ {
+ summary: "Load refused.",
+ detail: "Try again after the current task finishes.",
+ },
+ );
+});
+
+test("only diagnostic block boundaries are stripped", () => {
+ const message = "Check llama-server output: for details.";
+ assert.deepEqual(loadFailureToastParts(message), {
+ summary: message,
+ detail: "",
+ });
+});