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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Diffusion GGUFs are valid files, so they must not get the generic invalid-file or OOM message."""
from __future__ import annotations
import os
import sys
import types as _types
from pathlib import Path
import pytest
_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
if _BACKEND_DIR not in sys.path:
sys.path.insert(0, _BACKEND_DIR)
_loggers_stub = _types.ModuleType("loggers")
_loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
sys.modules.setdefault("loggers", _loggers_stub)
# A bare ModuleType structlog stub poisons later tests that call get_logger.
_structlog_stub = _types.ModuleType("structlog")
_structlog_stub.get_logger = lambda *a, **k: __import__("logging").getLogger("structlog")
sys.modules.setdefault("structlog", _structlog_stub)
if not hasattr(sys.modules["structlog"], "get_logger"):
sys.modules["structlog"].get_logger = _structlog_stub.get_logger
from core.inference.llama_cpp import LlamaCppBackend # noqa: E402
import time
_classify = LlamaCppBackend._classify_llama_start_failure
_QWEN_IMAGE_OUT = (
"load_model: loading model 'qwen-image-edit-2511-Q4_K_M.gguf'\n"
"llama_model_load: error loading model: unknown model architecture: 'qwen_image'\n"
"llama_model_load_from_file_impl: failed to load model"
)
_OOM_OUT = (
"ggml_backend_cuda_buffer_type_alloc_buffer: allocating 12000.00 MiB on "
"device 0: cudaMalloc failed: out of memory"
)
class TestDiffusionArchitectures:
def test_qwen_image_routes_to_images_page(self):
msg = _classify(_QWEN_IMAGE_OUT, "/models/qwen-image.gguf", "local/qwen-image")
assert "diffusion" in msg.lower()
assert "Images page" in msg
assert "qwen_image" in msg
assert "out of memory" not in msg.lower()
assert "enough memory" not in msg.lower()
@pytest.mark.parametrize("arch", sorted(LlamaCppBackend._IMAGE_ARCHES))
def test_every_image_arch_is_recognised(self, arch):
out = f"error loading model: unknown model architecture: '{arch}'"
msg = _classify(out, f"/models/{arch}.gguf", f"local/{arch}")
assert "diffusion" in msg.lower()
assert "Images page" in msg
assert arch in msg
def test_an_image_arch_this_host_cannot_build_promises_no_page(self, monkeypatch):
import core.inference.diffusion_engine_router as router
monkeypatch.setattr(router, "family_buildable_here", lambda fam, *, model_kind: False)
out = "error loading model: unknown model architecture: 'qwen_image21'"
msg = _classify(out, "/models/qwen-image-2.1-Q4_K_M.gguf", "unsloth/Qwen-Image-2.1-GGUF")
assert "qwen_image21" in msg
assert "Use Unsloth's Images page to generate" not in msg
assert "does not list it either" in msg
# A video arch must name the VIDEO page: Images cannot run it either.
@pytest.mark.parametrize("arch", sorted(LlamaCppBackend._VIDEO_ARCHES))
def test_every_video_arch_routes_to_the_video_page(self, arch):
out = f"error loading model: unknown model architecture: '{arch}'"
msg = _classify(out, f"/models/{arch}.gguf", f"local/{arch}")
assert "text-to-video" in msg.lower()
assert "Video page" in msg
assert "Images page" not in msg
assert arch in msg
assert "enough memory" not in msg.lower()
@pytest.mark.parametrize("arch", sorted(LlamaCppBackend._UNRUNNABLE_MEDIA_ARCHES))
def test_unrunnable_media_arch_names_no_page(self, arch):
out = f"error loading model: unknown model architecture: '{arch}'"
msg = _classify(out, f"/models/{arch}.gguf", f"local/{arch}")
assert arch in msg
assert "neither the Images page nor the Video page" in msg
assert "Use Unsloth's image generation page" not in msg
assert "Open it from" not in msg
assert "cannot run" in msg.lower()
assert "enough memory" not in msg.lower()
@pytest.mark.parametrize("arch", sorted(LlamaCppBackend._SPEECH_ARCHES))
def test_every_speech_arch_routes_to_the_audio_page(self, arch):
out = f"error loading model: unknown model architecture: '{arch}'"
msg = _classify(out, f"/models/{arch}.gguf", f"local/{arch}")
assert "text-to-speech" in msg.lower()
assert "Audio page" in msg
assert "Images page" not in msg
assert arch in msg
def test_media_arch_sets_are_disjoint_and_cover_the_union(self):
sets = (
LlamaCppBackend._IMAGE_ARCHES,
LlamaCppBackend._AMBIGUOUS_IMAGE_ARCHES,
LlamaCppBackend._VIDEO_ARCHES,
LlamaCppBackend._UNRUNNABLE_MEDIA_ARCHES,
)
assert sum(len(s) for s in sets) == len(set().union(*sets))
assert set().union(*sets) == LlamaCppBackend._DIFFUSION_ARCHES
def test_no_runnable_video_arch_is_tagged_unsupported_by_the_picker(self):
from routes.models import _UNSUPPORTED_DIFFUSION_GGUF_ARCHS
assert not (LlamaCppBackend._VIDEO_ARCHES & _UNSUPPORTED_DIFFUSION_GGUF_ARCHS)
class TestUnsupportedNonDiffusionArchitecture:
def test_unknown_llm_arch_says_unsupported_not_oom(self):
out = "error loading model: unknown model architecture: 'some_new_llm'"
msg = _classify(out, "/models/x.gguf", "local/x")
assert "some_new_llm" in msg
assert "architecture" in msg.lower()
assert "enough memory" not in msg.lower()
assert "diffusion" not in msg.lower()
def test_an_unknown_llm_arch_points_at_the_build_not_at_the_file(self):
"""An unknown architecture points at updating llama.cpp, since an older build is the usual cause."""
out = "error loading model: unknown model architecture: 'qwen4exp'"
msg = _classify(out, "/models/x.gguf", "local/x")
assert "qwen4exp" in msg
assert "updating llama.cpp" in msg.lower()
assert "cannot be run" not in msg.lower()
def test_a_parakeet_cpp_arch_does_not_blame_an_old_llama_cpp(self):
"""mudler/parakeet.cpp GGUFs must not get the 'update llama.cpp' toast (#16273)."""
out = "error loading model: unknown model architecture: 'parakeet'"
msg = _classify(out, "/models/parakeet-tdt.gguf", "mudler/parakeet-cpp-gguf")
assert "parakeet" in msg.lower()
assert "updating llama.cpp will not" in msg.lower()
assert "Parakeet-TDT-0.6B-v3-GGUF" in msg
assert "does not recognise" not in msg.lower()
assert "Images page" not in msg
@pytest.mark.parametrize(
"arch",
[
"taiwan",
"swan_llm",
"fluxion",
"sd1234",
"sd3_chat",
"aura2_text",
"cosmos_reason",
"qwen_image_text",
],
)
def test_arch_containing_diffusion_token_is_not_misrouted(self, arch):
out = f"error loading model: unknown model architecture: '{arch}'"
msg = _classify(out, f"/models/{arch}.gguf", f"local/{arch}")
assert arch in msg
assert "does not recognise" in msg.lower()
assert "diffusion" not in msg.lower()
assert "Images page" not in msg
class TestOllamaAndFallback:
_OLLAMA_GGUF = f"/home/u/.ollama{__import__('os').sep}ollama_links{__import__('os').sep}m.gguf"
def test_ollama_compat_message_still_works(self):
out = "llama_model_load: error loading model: key not found"
msg = _classify(out, self._OLLAMA_GGUF, "ollama/llama3")
assert "Ollama" in msg
def test_ollama_unknown_arch_keeps_ollama_guidance(self):
out = "error loading model: unknown model architecture: 'some_new_llm'"
msg = _classify(out, self._OLLAMA_GGUF, "ollama/some-new")
assert "Ollama" in msg
assert "directly through Ollama" in msg
assert "does not recognise" not in msg.lower()
def test_ollama_diffusion_arch_still_routes_to_images(self):
out = "error loading model: unknown model architecture: 'flux'"
msg = _classify(out, self._OLLAMA_GGUF, "ollama/flux")
assert "diffusion" in msg.lower()
assert "Images page" in msg
def test_missing_gguf_key_names_key_not_memory(self):
# #8513: a MiniMax-M3 GGUF made before llama.cpp's native MSA support.
out = (
"llama_model_load: error loading model: error loading model hyperparameters: "
"key not found in model: minimax-m3.attention.indexer.head_count\n"
"llama_model_load_from_file_impl: failed to load model\n"
)
msg = _classify(
out, "/models/MiniMax-M3-UD-Q6_K_XL-00001-of-00009.gguf", "unsloth/MiniMax-M3-GGUF", 1
)
assert "'minimax-m3.attention.indexer.head_count'" in msg
assert "not a memory problem" in msg
assert "updated GGUF" in msg
assert "GGUF file is valid" not in msg
assert "minimax-m3.attention.indexer.head_count\n" in msg
@pytest.mark.parametrize(
"line, named",
[
# #11259 comment, prism-ml/Ternary-Bonsai-2-27B-gguf PQ2_0 on the bundled build.
(
"gguf_init_from_reader: tensor 'output.weight' has invalid ggml type 142. "
"should be in [0, 67)\n"
"gguf_init_from_reader: failed to read tensor info\n",
"quantization type 142",
),
# #13908, KittenML/kitten-tts-2 TQ2_1 on b11696-mix: an id below the bundled count.
(
"gguf_init_from_reader: tensor 'blk.0.ffn_down.weight' of type 43 ((null)) has "
"6144 elements per row, not a multiple of block size (0)\n"
"gguf_init_from_reader: failed to read tensor info\n",
"quantization type 43",
),
# #11259 report: a group-128 Q2_0 tensor where the build defines group-64 Q2_0.
(
"gguf_init_from_reader: tensor 'dspark.fc.weight' has offset 337718592, "
"expected 357584192\n"
"gguf_init_from_reader: failed to read tensor data\n",
"download it again",
),
],
)
def test_unreadable_tensor_type_names_the_build_not_memory(self, line, named):
out = (
"load_model: loading model 'Ternary-Bonsai-27B-PQ2_0.gguf'\n"
+ line
+ "llama_model_load: error loading model: llama_model_loader: failed to load model\n"
"srv llama_server: exiting due to model loading error\n"
)
msg = _classify(
out, "/models/Ternary-Bonsai-27B-PQ2_0.gguf", "prism-ml/Ternary-Bonsai-27B-gguf", 1
)
assert named in msg
assert "download it again" in msg
assert "not a memory problem" in msg
assert "another quant" in msg
assert "GGUF file is valid" not in msg
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 "
"within the file bounds, model is corrupted or incomplete\n"
"llama_model_load_from_file_impl: failed to load model\n"
)
msg = _classify(out, "/models/m.gguf", "local/m", 1)
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.
out = (
"gguf_init_from_reader: tensor 'blk.0.ffn_down.weight' of type 12 (q4_K) has "
"6100 elements per row, not a multiple of block size (256)\n"
"gguf_init_from_reader: failed to read tensor info\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
def test_gpu_oom_has_actionable_memory_guidance(self):
msg = _classify(_OOM_OUT, "/models/big.gguf", "local/big")
assert "Couldn't allocate memory" in msg
assert "diffusion" not in msg.lower()
def test_empty_output_is_safe(self):
msg = _classify("", None, None)
assert "llama-server failed to start" in msg
def test_health_timeout_names_probe_not_generic(self):
msg = _classify(
"llama-server health check timed out: no startup progress for 600s",
"/models/x.gguf",
"local/x",
)
assert "/health" in msg
assert "NO_PROXY" in msg
assert "GGUF file is valid" not in msg
class TestOsKillReturncode:
"""SIGKILL with no output names OOM; SIGTERM stays neutral; -11 keeps the generic fallback."""
def test_sigkill_with_no_output_names_oom(self, monkeypatch):
# Pin the platform: macOS SIGKILL wording differs (see TestMacOSLoaderFailures).
monkeypatch.setattr(sys, "platform", "linux")
msg = _classify("", "/models/big-bf16.gguf", "local/big", -9)
assert "signal 9" in msg
assert "out of memory" in msg.lower()
assert ".wslconfig" in msg
assert "code signature" not in msg.lower()
assert "GGUF file is valid" not in msg
def test_sigterm_is_neutral_not_oom(self):
msg = _classify("", "/models/big-bf16.gguf", "local/big", -15)
assert "signal 15" in msg
assert "terminated" in msg.lower()
assert "out of memory" not in msg.lower()
def test_specific_output_wins_over_os_kill_code(self):
msg = _classify(_QWEN_IMAGE_OUT, "/models/qwen-image.gguf", "local/qwen-image", -9)
assert "diffusion" in msg.lower()
assert "out of memory" not in msg.lower()
def test_signal_crash_code_keeps_generic_message(self):
msg = _classify("", "/models/x.gguf", "local/x", -11)
assert "GGUF file is valid" in msg
assert "out of memory" not in msg.lower()
class TestMissingSharedLibrary:
"""The loader stops llama-server before it prints, so a missing libgomp.so.1 is not a bad GGUF."""
_LOADER_OUT = (
"/home/tester/.unsloth/llama.cpp/llama-server: error while loading "
"shared libraries: libgomp.so.1: cannot open shared object file: "
"No such file or directory"
)
def test_missing_libgomp_is_named_with_its_packages(self):
msg = _classify(self._LOADER_OUT, "/models/x.gguf", "local/x", 127)
assert "libgomp.so.1" in msg
assert "libgomp1" in msg
assert "Fedora/RHEL" in msg
assert "GGUF file is valid" not in msg
assert "enough memory" not in msg.lower()
def test_unknown_library_is_still_named(self):
out = "llama-server: error while loading shared libraries: libfoo.so.7: cannot open"
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "libfoo.so.7" in msg
assert "package manager" in msg
assert "libgomp1" not in msg
def test_exit_127_with_no_output_names_both_causes(self):
msg = _classify("", "/models/x.gguf", "local/x", 127)
assert "could not be found or run" in msg
assert "shared libraries" in msg
assert "package manager" not in msg
assert "GGUF file is valid" not in msg
assert "enough memory" not in msg.lower()
def test_exit_127_on_a_pinned_binary_does_not_send_it_to_the_updater(self, monkeypatch):
monkeypatch.setenv("LLAMA_SERVER_PATH", "/opt/custom/llama-server")
msg = _classify("", "/models/x.gguf", "local/x", 127, "/opt/custom/llama-server")
assert "unsloth studio update" not in msg
assert "custom llama.cpp" in msg
def test_exit_127_on_a_managed_binary_still_points_at_the_updater(self):
msg = _classify("", "/models/x.gguf", "local/x", 127)
assert "unsloth studio update" in msg
def test_wrapper_exec_failure_is_not_called_a_system_library(self):
out = (
"/home/t/.unsloth/llama.cpp/llama-server: 2: exec: ./build/bin/llama-server: not found"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "package manager" not in msg
assert "could not be found or run" in msg
def test_symbol_lookup_error_is_not_called_a_system_library(self):
out = "llama-server: symbol lookup error: llama-server: undefined symbol: ggml_backend_init"
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "package manager" not in msg
assert "HIP/ROCR" not in msg
assert "hsa_amd_queue_create" not in msg
def test_bundled_runtime_library_points_at_the_installer(self):
out = (
"/home/t/.unsloth/llama.cpp/build/bin/llama-server: error while loading "
"shared libraries: libggml.so.0: cannot open shared object file: "
"No such file or directory"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "libggml.so.0" in msg
assert "unsloth studio update" in msg
assert "package manager" not in msg
def test_corrupt_library_is_not_reported_as_missing(self):
out = (
"/opt/llama/llama-server: error while loading shared libraries: "
"/usr/lib/x86_64-linux-gnu/libgomp.so.1: file too short"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "file too short" in msg
assert "is missing" not in msg
assert "Install it with your package manager" not in msg
def test_corrupt_bundled_library_points_at_the_installer(self):
out = (
"llama-server: error while loading shared libraries: "
"/home/t/.unsloth/llama.cpp/build/bin/libggml-cuda.so: invalid ELF header"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "invalid ELF header" in msg
assert "unsloth studio update" in msg
assert "is missing" not in msg
def test_permission_denied_library_is_not_reported_as_missing(self):
out = (
"/opt/llama/llama-server: error while loading shared libraries: "
"/opt/llama/lib/libgomp.so.1: cannot open shared object file: "
"Permission denied"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "Permission denied" in msg
assert "is missing" not in msg
assert "package manager" not in msg
def test_permission_denied_bundled_library_is_not_reported_as_missing(self):
out = (
"/home/t/.unsloth/llama.cpp/build/bin/llama-server: error while loading "
"shared libraries: /home/t/.unsloth/llama.cpp/build/bin/libggml.so: "
"cannot open shared object file: Permission denied"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "Permission denied" in msg
assert "is missing" not in msg
def test_library_path_with_spaces_is_named_in_full(self):
out = (
"/opt/llama/llama-server: error while loading shared libraries: "
"/opt/My Runtime/libfoo.so: file too short"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "/opt/My Runtime/libfoo.so" in msg
assert "file too short" in msg
def test_missing_library_path_with_spaces_is_named_in_full(self):
out = (
"/opt/llama/llama-server: error while loading shared libraries: "
"/opt/My Runtime/libbar.so: cannot open shared object file: "
"No such file or directory"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "/opt/My Runtime/libbar.so" in msg
assert "is missing" in msg
def test_an_absolute_path_is_not_offered_to_a_package_manager(self):
out = (
"llama-server: error while loading shared libraries: "
"/opt/vendor/libaccelerator.so: cannot open shared object file: "
"No such file or directory"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "/opt/vendor/libaccelerator.so" in msg
assert "package manager" not in msg
assert "that exact location" in msg
def test_an_absolute_path_on_a_pinned_binary_names_the_custom_runtime(self, monkeypatch):
monkeypatch.setenv("LLAMA_SERVER_PATH", "/opt/custom/llama-server")
out = (
"llama-server: error while loading shared libraries: "
"/opt/vendor/libaccelerator.so: cannot open shared object file: "
"No such file or directory"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127, "/opt/custom/llama-server")
assert "custom llama.cpp" in msg
assert "unsloth studio update" not in msg
assert "package manager" not in msg
def test_a_bare_soname_keeps_package_advice_even_on_a_pinned_binary(self, monkeypatch):
monkeypatch.setenv("LLAMA_SERVER_PATH", "/opt/custom/llama-server")
out = (
"llama-server: error while loading shared libraries: "
"libgomp.so.1: cannot open shared object file: No such file or directory"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127, "/opt/custom/llama-server")
assert "libgomp1" in msg
assert "package manager" in msg
def test_a_relative_dt_needed_is_an_exact_path_too(self):
# glibc skips search when the name has any '/', so relative paths name one exact file.
out = (
"llama-server: error while loading shared libraries: "
"subdir/libvendor.so: cannot open shared object file: "
"No such file or directory"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "subdir/libvendor.so" in msg
assert "package manager" not in msg
assert "that exact location" in msg
def test_a_windows_absolute_path_is_recognised_too(self):
out = (
"llama-server: error while loading shared libraries: "
"C:\\vendor\\accel.dll: cannot open shared object file: "
"No such file or directory"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "package manager" not in msg
assert "that exact location" in msg
def test_bundled_library_under_a_spaced_path_still_points_at_the_installer(self):
out = (
"llama-server: error while loading shared libraries: "
"/home/My User/.unsloth/llama.cpp/build/bin/libggml.so: invalid ELF header"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "/home/My User/.unsloth/llama.cpp/build/bin/libggml.so" in msg
assert "unsloth studio update" in msg
def test_pinned_custom_binary_is_not_called_unsloths_runtime(self, monkeypatch):
monkeypatch.setenv("LLAMA_SERVER_PATH", "/opt/mybuild/bin/llama-server")
out = (
"/opt/mybuild/bin/llama-server: error while loading shared libraries: "
"libggml.so: cannot open shared object file: No such file or directory"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127, "/opt/mybuild/bin/llama-server")
assert "libggml.so" in msg
assert "unsloth studio update" not in msg
assert "package manager" not in msg
assert "custom install" in msg
def test_managed_binary_still_points_at_the_installer(self, monkeypatch, tmp_path):
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
binary = tmp_path / "llama.cpp" / "build" / "bin" / "llama-server"
binary.parent.mkdir(parents = True)
binary.write_text("")
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(tmp_path / "llama.cpp"))
out = (
f"{binary}: error while loading shared libraries: libggml.so: "
"cannot open shared object file: No such file or directory"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127, str(binary))
assert "unsloth studio update" in msg
def test_nameless_loader_error_does_not_invent_a_library(self):
out = "llama-server: error while loading shared libraries: cannot create search path array"
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "cannot create search path array" in msg
assert "the library cannot" not in msg
assert "is missing" not in msg
def test_loader_error_wins_without_a_returncode(self):
msg = _classify(self._LOADER_OUT, "/models/x.gguf", "local/x")
assert "libgomp.so.1" in msg
def test_a_normal_failure_is_untouched(self):
msg = _classify(_OOM_OUT, "/models/big.gguf", "local/big", 1)
assert "Couldn't allocate memory" in msg
assert "system library" not in msg
def test_a_named_arch_wins_over_exit_127(self):
msg = _classify(_QWEN_IMAGE_OUT, "/models/qwen-image.gguf", "local/qwen-image", 127)
assert "Images page" in msg
assert "system library" not in msg
class TestBundledHipRocrMismatch:
"""A HIP/ROCr symbol lookup failure (exit 127) is a runtime mismatch, not a missing binary."""
_FIELD_OUT = (
"0.00.018.048 I srv load_model: loading model '/models/x.gguf'\n"
"/home/t/.unsloth/llama.cpp/llama-server: symbol lookup error: "
"/home/t/.unsloth/llama.cpp/build/bin/libamdhip64.so.7: "
"undefined symbol: hsa_amd_queue_create, version ROCR_1"
)
def test_field_log_is_the_hip_rocr_mix(self):
assert LlamaCppBackend._is_bundled_hip_rocr_mismatch(self._FIELD_OUT)
def test_ggml_symbol_lookup_is_not_the_hip_rocr_mix(self):
out = (
"llama-server: symbol lookup error: llama-server: "
"undefined symbol: ggml_backend_init"
)
assert not LlamaCppBackend._is_bundled_hip_rocr_mismatch(out)
def test_missing_libamdhip64_is_not_the_hip_rocr_mix(self):
out = (
"llama-server: error while loading shared libraries: "
"libamdhip64.so.7: cannot open shared object file: "
"No such file or directory"
)
assert not LlamaCppBackend._is_bundled_hip_rocr_mismatch(out)
def test_empty_and_none_are_not_the_mix(self):
assert not LlamaCppBackend._is_bundled_hip_rocr_mismatch("")
assert not LlamaCppBackend._is_bundled_hip_rocr_mismatch(None)
def test_another_lib_from_the_prepended_dir_is_the_same_mix(self):
out = (
"llama-server: symbol lookup error: "
"/home/t/.unsloth/llama.cpp/build/bin/librocblas.so.4: "
"undefined symbol: hipGraphicsResourceGetMappedPointer"
)
assert LlamaCppBackend._is_bundled_hip_rocr_mismatch(out)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "librocblas.so.4" in msg
assert "hipGraphicsResourceGetMappedPointer" in msg
assert "hsa_amd_queue_create" not in msg
def test_an_oversized_loader_token_is_bounded_in_the_message(self):
out = (
"llama-server: symbol lookup error: "
f"/b/libamdhip64.so.{'9' * 3000}: undefined symbol: {'s' * 8192}"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "HIP/ROCR" in msg
assert len(msg) < 1000
def test_an_object_longer_than_a_path_is_not_the_mix(self):
# Capture stops at PATH_MAX so a hostile line cannot make the scan quadratic.
out = (
"llama-server: symbol lookup error: "
f"/b/libamdhip64.so.{'9' * 8192}: undefined symbol: hsa_amd_queue_create"
)
assert not LlamaCppBackend._is_bundled_hip_rocr_mismatch(out)
def test_a_bundle_under_a_path_with_spaces_is_still_the_mix(self):
out = (
"llama-server: symbol lookup error: "
"/opt/My Runtime/build/bin/libamdhip64.so.7: "
"undefined symbol: hsa_amd_queue_create, version ROCR_1"
)
assert LlamaCppBackend._is_bundled_hip_rocr_mismatch(out)
assert LlamaCppBackend._bundled_hip_symbol_miss(out)[0].endswith(
"/opt/My Runtime/build/bin/libamdhip64.so.7"
)
assert "libamdhip64.so.7" in _classify(out, "/models/x.gguf", "local/x", 127)
def test_a_path_component_does_not_stand_in_for_the_object(self):
out = (
"llama-server: symbol lookup error: "
"/opt/librocm-vendor/lib/libfoo.so.1: undefined symbol: foo_init"
)
assert not LlamaCppBackend._is_bundled_hip_rocr_mismatch(out)
def test_classify_names_the_mix_not_a_missing_binary(self):
msg = _classify(self._FIELD_OUT, "/models/x.gguf", "local/x", 127)
assert "HIP/ROCR" in msg
assert "hsa_amd_queue_create" in msg
assert "Vulkan" in msg
assert "could not be found or run" not in msg
assert "not out of VRAM" in msg
assert "GGUF file is valid" not in msg
assert "enough memory" not in msg.lower()
def test_classify_on_a_pinned_binary_does_not_send_it_to_the_updater(self, monkeypatch):
monkeypatch.setenv("LLAMA_SERVER_PATH", "/opt/custom/llama-server")
msg = _classify(
self._FIELD_OUT, "/models/x.gguf", "local/x", 127, "/opt/custom/llama-server"
)
assert "unsloth studio update" not in msg
assert "custom llama.cpp" in msg
def test_hip_rocr_retry_is_checked_before_the_fit_on_retry(self):
src = Path(__file__).resolve().parent.parent / "core" / "inference" / "llama_cpp.py"
text = src.read_text(encoding = "utf-8")
spawn_start = text.index("def _spawn_and_wait(")
spawn_end = text.index("def _raise_terminal_load_failure", spawn_start)
body = text[spawn_start:spawn_end]
assert body.index("_is_bundled_hip_rocr_mismatch") < body.index(
"retrying once with --fit on so it can offload"
)
assert "use_system_rocm = False" in body
_DYLD_MISSING_OUT = (
"dyld[54231]: Library not loaded: @rpath/libllama.dylib\n"
" Referenced from: <A1B2C3D4> /Users/me/.unsloth/studio/llama.cpp/build/bin/llama-server\n"
" Reason: tried: '/Users/me/.unsloth/studio/llama.cpp/build/bin/libllama.dylib' "
"(no such file), '/usr/local/lib/libllama.dylib' (no such file)"
)
_DYLD_OLD_MACOS_OUT = (
"dyld: Library not loaded: @rpath/libggml-metal.dylib\n"
" Referenced from: /Users/me/.unsloth/studio/llama.cpp/build/bin/llama-server\n"
" Reason: image not found"
)
_DYLD_SIGNATURE_OUT = (
"dyld[54231]: Library not loaded: @rpath/libggml-base.dylib\n"
" Reason: tried: '/Users/me/.unsloth/studio/llama.cpp/build/bin/libggml-base.dylib' "
"(code signature in <A1B2> '.../libggml-base.dylib' not valid for use in process: "
"mapped file has no cdhash, completely unsigned? Code has to be at least ad-hoc signed.)"
)
_DYLD_ARCH_OUT = (
"dyld[54231]: Library not loaded: @rpath/libmtmd.dylib\n"
" Reason: tried: '/Users/me/.unsloth/studio/llama.cpp/build/bin/libmtmd.dylib' "
"(mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64'))"
)
_DYLD_TOO_NEW_OUT = (
"dyld[54231]: Library not loaded: @rpath/libggml-metal.dylib\n"
" Reason: tried: '.../libggml-metal.dylib' (built for macOS 26.0 which is "
"newer than running OS)"
)
_DYLD_SYMBOL_OUT = (
"dyld[54231]: Symbol not found: __ZN4ggml7backend6deviceEv\n"
" Referenced from: <A1B2> /Users/me/.unsloth/studio/llama.cpp/build/bin/libmtmd.dylib\n"
" Expected in: <C3D4> /Users/me/.unsloth/studio/llama.cpp/build/bin/libllama.dylib"
)
def _blames_the_gguf_or_memory(msg: str) -> bool:
lowered = msg.lower()
return "gguf file is valid" in lowered or "enough memory" in lowered
class TestMacOSLoaderFailures:
def test_missing_dylib_names_the_library_and_the_installer(self):
msg = _classify(_DYLD_MISSING_OUT, "/models/x.gguf", "local/x", 1)
assert "libllama.dylib" in msg
assert "unsloth studio update" in msg
assert not _blames_the_gguf_or_memory(msg)
def test_old_macos_image_not_found_is_recognised(self):
msg = _classify(_DYLD_OLD_MACOS_OUT, "/models/x.gguf", "local/x", 1)
assert "libggml-metal.dylib" in msg
assert not _blames_the_gguf_or_memory(msg)
def test_invalid_code_signature_is_not_reported_as_a_bad_file(self):
msg = _classify(_DYLD_SIGNATURE_OUT, "/models/x.gguf", "local/x", 1)
assert "code signature" in msg.lower()
assert not _blames_the_gguf_or_memory(msg)
def test_wrong_architecture_is_named(self):
msg = _classify(_DYLD_ARCH_OUT, "/models/x.gguf", "local/x", 1)
assert "architecture" in msg.lower()
assert not _blames_the_gguf_or_memory(msg)
def test_runtime_built_for_a_newer_macos(self):
msg = _classify(_DYLD_TOO_NEW_OUT, "/models/x.gguf", "local/x", 1)
assert "newer version of macOS" in msg
assert not _blames_the_gguf_or_memory(msg)
def test_mtlresidency_symbol_is_read_as_a_too_new_macos_build(self):
out = (
"dyld[1]: Symbol not found: _MTLResidencySetDescriptor\n"
" Referenced from: .../libggml-metal.dylib"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "newer version of macOS" in msg
def test_symbol_mismatch_reports_a_mixed_install(self):
msg = _classify(_DYLD_SYMBOL_OUT, "/models/x.gguf", "local/x", 1)
assert "different build" in msg
assert not _blames_the_gguf_or_memory(msg)
def test_dyld_output_outranks_signal_9(self):
# A dyld diagnostic must win over -9, which otherwise reads as the OOM killer.
msg = _classify(_DYLD_MISSING_OUT, "/models/x.gguf", "local/x", -9)
assert "libllama.dylib" in msg
assert "out of memory" not in msg.lower()
def test_custom_binary_is_not_sent_to_the_unsloth_updater(self, monkeypatch):
monkeypatch.setenv("LLAMA_SERVER_PATH", "/opt/mybuild/bin/llama-server")
msg = _classify(
_DYLD_ARCH_OUT, "/models/x.gguf", "local/x", 1, "/opt/mybuild/bin/llama-server"
)
assert "unsloth studio update" not in msg
assert "custom llama.cpp" in msg
def test_linux_loader_wording_is_untouched(self):
out = (
"llama-server: error while loading shared libraries: libgomp.so.1: "
"cannot open shared object file: No such file or directory"
)
msg = _classify(out, "/models/x.gguf", "local/x", 127)
assert "libgomp.so.1" in msg
assert "macOS" not in msg
def test_silent_signal_9_on_macos_also_names_the_code_signature(self, monkeypatch):
# macOS SIGKILLs a bad code signature silently, indistinguishable from OOM by returncode.
monkeypatch.setattr(sys, "platform", "darwin")
msg = _classify("", "/models/x.gguf", "local/x", -9)
assert "code signature" in msg.lower()
assert "out of memory" in msg.lower()
def test_ordinary_output_mentioning_reason_is_not_a_loader_failure(self):
out = "llama_model_load: error loading model: Reason: something went wrong"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "llama-server failed to start." in msg
class TestANonGgufFile:
_OUT = (
"build: 9415 (06d26dfd) with Apple clang version 17.0.0 for arm64-apple-darwin24.6.0\n"
"gguf_init_from_reader: invalid magic characters: '\ufffd\ufffd\ufffd\ufffd', "
"expected 'GGUF'\n"
"llama_server: exiting due to model loading error"
)
def test_it_is_reported_as_not_a_gguf(self, tmp_path):
log = tmp_path / "llama-1-port-8080.log"
msg = _classify(self._OUT, "/models/._muse-UD-Q2_K_XL.gguf", "local/muse", 1, None, log)
assert "not a GGUF" in msg
assert "enough memory" not in msg.lower()
assert not msg.startswith("llama-server failed to start.")
assert "._muse-UD-Q2_K_XL.gguf" in msg
assert "companion" in msg
assert "dot_clean -m" in msg
assert "llama-server output:" in msg
assert f"Full log: {log}" in msg
def test_it_does_not_call_an_ordinary_main_model_the_bad_file(self):
assert "is not a GGUF" in _classify(self._OUT, None, "local/muse", 1)
msg = _classify(self._OUT, "/models/model-Q4_K_M.gguf", "local/m", 1)
assert "model-Q4_K_M.gguf" in msg and "companion" in msg
assert "names it" not in msg
assert "dot_clean" not in msg and "Re-download the model" in msg
def test_a_dyld_failure_still_outranks_it(self):
out = (
"dyld[1]: Library not loaded: @rpath/libggml.dylib\n"
"gguf_init_from_reader: invalid magic characters: '????', expected 'GGUF'"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "not a GGUF" not in msg
class TestStartupDiagnostics:
_UNKNOWN_OUT = (
"build: 9415 (06d26dfd) with Apple clang version 17.0.0 for arm64-apple-darwin24.6.0\n"
"GGML_ASSERT(ctx->device != nil) failed"
)
def test_unknown_failure_carries_the_output_tail(self):
msg = _classify(self._UNKNOWN_OUT, "/models/x.gguf", "local/x", 1)
assert msg.startswith("llama-server failed to start.")
assert "GGML_ASSERT" in msg
assert "llama-server output:" in msg
def test_unknown_failure_carries_the_log_path(self, tmp_path):
log = tmp_path / "llama-1-port-8080.log"
msg = _classify(self._UNKNOWN_OUT, "/models/x.gguf", "local/x", 1, None, log)
assert f"Full log: {log}" in msg
def test_the_tail_is_bounded(self):
out = "x" * 50_000 + "\nfinal line"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "final line" in msg
assert len(msg) < 4000
def test_control_characters_are_stripped(self):
out = "loading \x1b[32mmodel\x1b[0m \x00done"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "\x00" not in msg
assert "\x1b" not in msg
assert "done" in msg
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."
)
def test_a_classified_message_gains_no_diagnostics(self, tmp_path):
log = tmp_path / "llama-1-port-8080.log"
msg = _classify(_QWEN_IMAGE_OUT, "/models/q.gguf", "local/q", 1, None, log)
assert "Images page" in msg
assert "Full log" not in msg
assert "llama-server output:" not in msg
class TestMacOSLoaderEdgeCases:
"""dyld's real output shape: a mixed "tried:" list, unrelated text above it,
and a reason that can run for kilobytes."""
def test_a_mixed_tried_list_judges_our_own_copy(self, monkeypatch, tmp_path):
# Leftover Intel Homebrew dylibs must not be reported as a wrong-arch error.
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
binary = tmp_path / "llama.cpp" / "build" / "bin" / "llama-server"
binary.parent.mkdir(parents = True)
binary.write_text("")
out = (
"dyld[4210]: Library not loaded: @rpath/libmtmd.dylib\n"
f" Reason: tried: '{binary.parent}/libmtmd.dylib' (no such file), "
"'/usr/local/lib/libmtmd.dylib' (mach-o file, but is an incompatible "
"architecture (have 'x86_64', need 'arm64')), "
"'/usr/lib/libmtmd.dylib' (no such file, not in dyld cache)"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1, str(binary))
assert "libmtmd.dylib" in msg
assert "architecture" not in msg.lower()
assert "missing" in msg.lower()
def test_a_policy_blocked_sibling_does_not_accuse_the_user_of_tampering(
self, monkeypatch, tmp_path
):
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
binary = tmp_path / "llama.cpp" / "build" / "bin" / "llama-server"
binary.parent.mkdir(parents = True)
binary.write_text("")
out = (
"dyld[4210]: Library not loaded: @rpath/libllama.dylib\n"
f" Reason: tried: '{binary.parent}/libllama.dylib' (no such file), "
"'/usr/local/lib/libllama.dylib' (code signature not valid for use in "
"process: library load disallowed by system policy)"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1, str(binary))
assert "code signature" not in msg.lower()
assert "was modified" not in msg
def test_our_own_copy_really_is_the_signature_failure(self, monkeypatch, tmp_path):
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
binary = tmp_path / "llama.cpp" / "build" / "bin" / "llama-server"
binary.parent.mkdir(parents = True)
binary.write_text("")
out = (
"dyld[4210]: Library not loaded: @rpath/libllama.dylib\n"
f" Reason: tried: '{binary.parent}/libllama.dylib' (code signature in "
"<A1B2> not valid for use in process: mapped file has no cdhash)"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1, str(binary))
assert "code signature" in msg.lower()
def test_an_earlier_unrelated_reason_is_not_read_as_dylds(self):
out = (
"main: loading model\n"
"llama_model_load: error loading model: Reason: unknown\n"
"ggml_metal_init: skipping device, incompatible architecture\n"
"dyld[9]: Library not loaded: @rpath/libggml-base.dylib\n"
" Reason: tried: '/x/libggml-base.dylib' (no such file)"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "libggml-base.dylib" in msg
assert "architecture" not in msg.lower()
def test_a_stray_reason_does_not_disable_symbol_classification(self):
out = (
"srv load: Reason: retrying\n"
"dyld[1]: Symbol not found: __ZN4ggml7backendE\n"
" Referenced from: /x/libmtmd.dylib\n"
" Expected in: /x/libllama.dylib"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "different build" in msg
def test_the_classified_reason_is_bounded(self):
out = (
"dyld[1]: Library not loaded: @rpath/libllama.dylib\n"
" Reason: no suitable image found. Did find: " + "x" * 20_000
)
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "libllama.dylib" in msg
assert len(msg) < 1000
def test_the_health_timeout_marker_is_not_absorbed_into_a_dyld_reason(self):
out = (
"dyld[1]: Library not loaded: @rpath/libllama.dylib\n"
" Reason: tried: '/x/libllama.dylib' (no such file)\n"
"llama-server health check timed out: no startup progress for 600s"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "health check timed out" not in msg
def test_signal_9_on_macos_respects_a_custom_binary(self, monkeypatch):
monkeypatch.setattr(sys, "platform", "darwin")
monkeypatch.setenv("LLAMA_SERVER_PATH", "/opt/mybuild/bin/llama-server")
msg = _classify("", "/models/x.gguf", "local/x", -9, "/opt/mybuild/bin/llama-server")
assert "unsloth studio update" not in msg
assert "custom llama.cpp" in msg
class TestDiagnosticsDoNotLeak:
"""The output tail can leak secrets because llama-server inherits Unsloth's environment."""
_OUT = "build: 9415\nenv dump: OPENAI_API_KEY=sk-owner-secret-1234567890\nabort"
def test_a_secret_env_value_is_redacted(self, monkeypatch):
monkeypatch.setenv("OPENAI_API_KEY", "sk-owner-secret-1234567890")
msg = _classify(self._OUT, "/models/x.gguf", "local/x", 1)
assert "sk-owner-secret-1234567890" not in msg
assert "***" in msg
def test_a_non_secret_env_value_is_left_alone(self, monkeypatch):
monkeypatch.setenv("UNSLOTH_MODEL_DIR", "/models/mymodels")
msg = _classify("loading from /models/mymodels failed", "/models/x.gguf", "local/x", 1)
assert "/models/mymodels" in msg
def test_a_credential_url_is_redacted_whatever_it_is_named(self, monkeypatch):
monkeypatch.setenv("DATABASE_URL", "postgres://admin:hunter2secret@db:5432/prod")
out = "dump: DATABASE_URL=postgres://admin:hunter2secret@db:5432/prod"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "hunter2secret" not in msg
def test_a_token_shape_is_redacted_under_an_unremarkable_name(self, monkeypatch):
monkeypatch.setenv("GITHUB_PAT", "github_pat_11ABCDEFG0123456789abcdefghij")
out = "dump: GITHUB_PAT=github_pat_11ABCDEFG0123456789abcdefghij"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "github_pat_11ABCDEFG0123456789abcdefghij" not in msg
def test_a_bare_hf_token_shape_is_redacted(self):
out = "curl -H 'Authorization: Bearer hf_" + "a" * 34 + "' failed"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "hf_" + "a" * 34 not in msg
def test_a_huge_unterminated_line_is_cheap(self):
# Proven by behaviour, not a stopwatch: wall-clock budgets flake on Windows runners.
buried = "error: invalid argument: --nope\n" + "x" * 10_000_000 + "\nggml_metal_init: error"
start = time.perf_counter()
msg = _classify(buried, "/models/x.gguf", "local/x", 1)
elapsed = time.perf_counter() - start
assert "--nope" not in msg
assert "ggml_metal_init: error" in msg
assert elapsed < 5, f"{elapsed:.1f}s to classify one 10 MB line"
def test_an_argument_error_inside_the_tail_is_still_reported(self):
out = "x" * 10_000_000 + "\nerror: invalid argument: --nope"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "--nope" in msg
class TestDyldInstallNames:
def test_an_rpath_placeholder_is_not_reported_as_a_location(self, monkeypatch):
monkeypatch.setenv("LLAMA_SERVER_PATH", "/opt/mybuild/bin/llama-server")
out = (
"dyld[1]: Library not loaded: @rpath/libomp.dylib\n"
" Reason: tried: '/opt/mybuild/bin/libomp.dylib' (no such file)"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1, "/opt/mybuild/bin/llama-server")
assert "@rpath" not in msg
assert "libomp.dylib" in msg
assert "that exact location" not in msg
def test_a_bundled_dylib_behind_rpath_still_points_at_the_installer(self, monkeypatch):
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
out = (
"dyld[1]: Library not loaded: @rpath/libggml-metal.dylib\n"
" Reason: tried: '/x/libggml-metal.dylib' (no such file)"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "unsloth studio update" in msg
class TestMacOSSymbolProvenance:
"""The symbol dyld expected decides the fix: reinstalling cannot make the OS export it."""
def test_a_system_framework_symbol_reads_as_a_too_new_build(self):
out = (
"dyld[1]: Symbol not found: _MTLDeviceNewCommandQueueWithDescriptor\n"
" Referenced from: /Users/me/.unsloth/llama.cpp/build/bin/libggml-metal.dylib\n"
" Expected in: /System/Library/Frameworks/Metal.framework/Versions/A/Metal"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "newer macOS" in msg
assert "different build than the llama-server binary" not in msg
def test_a_llama_dylib_symbol_still_reads_as_a_mixed_install(self):
out = (
"dyld[1]: Symbol not found: __ZN4ggml7backendE\n"
" Referenced from: /Users/me/.unsloth/llama.cpp/build/bin/libmtmd.dylib\n"
" Expected in: /Users/me/.unsloth/llama.cpp/build/bin/libllama.dylib"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "different build" in msg
assert "newer macOS" not in msg
def test_a_usr_lib_symbol_is_read_the_same_way_as_a_framework(self):
out = (
"dyld[1]: Symbol not found: _os_signpost_emit\n"
" Expected in: /usr/lib/libSystem.B.dylib"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "newer macOS" in msg
class TestCommandLineSecrets:
"""--api-key is minted per launch with secrets.token_urlsafe(32), so it is
in no environment variable and matches no token shape."""
_KEY = "Xy9_kQ2mLp7RtVw4NbZc8FgHjKdSaEuI0oPqWxYz1A"
def test_the_api_key_is_redacted_by_its_flag(self):
out = f"exec: llama-server -m x.gguf --api-key {self._KEY} --port 8080\nabort"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert self._KEY not in msg
assert "--api-key" in msg
def test_the_equals_form_is_redacted_too(self):
out = f"argv: --api-key={self._KEY}"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert self._KEY not in msg
def test_a_known_secret_is_redacted_wherever_it_appears(self):
out = f"client sent token {self._KEY} and was refused"
msg = _classify(out, "/models/x.gguf", "local/x", 1, None, None, (self._KEY,))
assert self._KEY not in msg
def test_no_known_secret_is_harmless(self):
msg = _classify("plain failure", "/models/x.gguf", "local/x", 1, None, None, (None,))
assert "plain failure" in msg
class TestClassifierScoping:
"""Pure text classifier runs everywhere, so a macOS diagnosis needs macOS evidence."""
def test_a_bare_symbol_not_found_is_not_a_macos_diagnosis(self):
out = "plugin loader: Symbol not found in module registry\nexiting"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "llama.cpp libraries are from" not in msg
assert "llama-server failed to start." in msg
assert "plugin loader" in msg
def test_dyld_framing_still_classifies(self):
out = (
"dyld[1]: Symbol not found: __ZN4ggml7backendE\n"
" Expected in: /Users/me/.unsloth/llama.cpp/build/bin/libllama.dylib"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "different build" in msg
class TestNestedDyldPlaceholders:
def test_a_nested_placeholder_is_reduced_to_the_library_name(self, monkeypatch):
monkeypatch.setenv("LLAMA_SERVER_PATH", "/opt/mybuild/bin/llama-server")
out = (
"dyld[1]: Library not loaded: @loader_path/../Frameworks/libomp.dylib\n"
" Reason: tried: '/opt/mybuild/Frameworks/libomp.dylib' (no such file)"
)
msg = _classify(out, "/models/x.gguf", "local/x", 1, "/opt/mybuild/bin/llama-server")
assert "libomp.dylib" in msg
assert "@loader_path" not in msg
assert "../Frameworks" not in msg
assert "that exact location" not in msg
class TestShortSecrets:
def test_a_short_password_is_redacted_beside_its_name(self, monkeypatch):
monkeypatch.setenv("DATABASE_PASSWORD", "hunter2")
out = "env dump: DATABASE_PASSWORD=hunter2 PORT=8080"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "hunter2" not in msg
assert "PORT=8080" in msg
def test_a_short_non_secret_value_is_not_replaced_globally(self, monkeypatch):
monkeypatch.setenv("UNSLOTH_PORT", "8080")
msg = _classify("bound 8080 then failed", "/models/x.gguf", "local/x", 1)
assert "8080" in msg
class TestDiagnosticsAreAFixedPoint:
"""Decorating a message twice must be a no-op, or the tail and log line would silently double."""
_OUT = "some unrecognised startup noise"
_LOG = "/Users/me/.unsloth/studio/logs/llama-server/llama-1-port-8080.log"
def test_appending_twice_adds_nothing(self):
once = LlamaCppBackend._with_startup_diagnostics("base", self._OUT, self._LOG)
assert once.count("llama-server output:") == 1
assert once.count("Full log: ") == 1
assert LlamaCppBackend._with_startup_diagnostics(once, self._OUT, self._LOG) == once
def test_a_classified_message_fed_back_in_is_not_decorated_twice(self):
once = _classify(self._OUT, "/models/x.gguf", "local/x", 1, None, log_path = self._LOG)
twice = LlamaCppBackend._with_startup_diagnostics(once, self._OUT, self._LOG)
assert twice == once
def test_a_tail_that_merely_mentions_the_label_is_still_decorated(self):
out = "llama-server output: 3 tokens/s\nthen it died"
msg = LlamaCppBackend._with_startup_diagnostics("base", out, None)
assert msg.startswith("base\n\nllama-server output:\n")
class TestTheDyldReasonIsBounded:
def test_a_pathological_reason_does_not_stall_the_classifier(self):
out = (
"dyld[1]: Library not loaded: @rpath/libllama.dylib\n"
" Reason: tried: " + "'a' (" * 20000
)
# CPU time, not wall clock (descheduling inflates it). Healthy ~0.01s, regression 6.3s.
start = time.process_time()
msg = _classify(
out,
"/models/x.gguf",
"local/x",
1,
"/Users/me/.unsloth/llama.cpp/build/bin/llama-server",
)
assert time.process_time() - start < 1.0
assert "libllama.dylib" in msg
def test_a_real_reason_is_not_truncated(self):
out = (
"dyld[1]: Library not loaded: @rpath/libggml-base.dylib\n"
" Reason: tried: '/Users/me/.unsloth/llama.cpp/build/bin/libggml-base.dylib' "
"(mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64'))"
)
msg = _classify(
out,
"/models/x.gguf",
"local/x",
1,
"/Users/me/.unsloth/llama.cpp/build/bin/llama-server",
)
assert "architecture" in msg
class TestOnlyDyldsOwnOutputIsReadAsDyld:
"""Only dyld's own lines count as dyld errors; model metadata echoed in stderr must not match."""
_BIN = "/Users/me/.unsloth/llama.cpp/build/bin/llama-server"
def test_metadata_does_not_beat_the_tensor_parallel_branch(self):
out = (
"llama_model_loader: - kv 2: general.name str = Symbol not found: MTLResidency\n"
"split_mode_tensor not implemented"
)
assert "Tensor parallelism" in _classify(out, "/m.gguf", "u/x", 1, self._BIN)
def test_metadata_does_not_beat_the_diffusion_branch(self):
out = (
"llama_model_loader: - kv 2: general.name str = Library not loaded: libfake.so\n"
"llama_model_load: error loading model architecture: "
"unknown model architecture: 'qwen_image'"
)
assert "diffusion" in _classify(out, "/m.gguf", "u/x", 1, self._BIN)
def test_metadata_does_not_beat_status_127(self):
msg = _classify(
"wrapper says Library not loaded: libx.so", "/m.gguf", "u/x", 127, self._BIN
)
assert "status 127" in msg
def test_metadata_does_not_beat_signal_15(self):
msg = _classify(
"wrapper says Library not loaded: libx.so", "/m.gguf", "u/x", -15, self._BIN
)
assert "signal 15" in msg
def test_metadata_does_not_claim_a_too_new_macos(self):
out = (
"llama_model_loader: - kv 9: general.description str = "
"built for macOS 26.0 which is newer than running OS"
)
msg = _classify(out, "/m.gguf", "u/x", 1, self._BIN)
assert "newer version of macOS" not in msg
def test_real_dyld_framing_still_classifies(self):
out = (
"dyld[4321]: Library not loaded: @rpath/libllama.dylib\n"
" Referenced from: <A> /Users/me/.unsloth/llama.cpp/build/bin/llama-server\n"
" Reason: tried: '/Users/me/.unsloth/llama.cpp/build/bin/libllama.dylib' (no such file)\n"
)
assert "libllama.dylib" in _classify(out, "/m.gguf", "u/x", 1, self._BIN)
def test_the_older_bare_dyld_prefix_is_framing_too(self):
out = "dyld: Library not loaded: @rpath/libllama.dylib\n Reason: image not found\n"
assert "libllama.dylib" in _classify(out, "/m.gguf", "u/x", 1, self._BIN)
class TestArchitectureAndQuotedPaths:
_BIN = "/Users/me/.unsloth/llama.cpp/build/bin/llama-server"
def test_a_quoted_system_framework_reads_as_a_too_new_build(self):
out = (
"dyld[5]: Symbol not found: _MTLFoo\n"
" Referenced from: <A> /Users/me/.unsloth/llama.cpp/build/bin/llama-server\n"
" Expected in: '/System/Library/Frameworks/Metal.framework/Versions/A/Metal'\n"
)
msg = _classify(out, "/m.gguf", "u/x", 1, self._BIN)
assert "newer macOS" in msg
assert "different build" not in msg
def test_the_older_wrong_architecture_wording_is_recognised(self):
out = (
"dyld[5]: Library not loaded: @rpath/libggml.dylib\n"
" Reason: tried: '/Users/me/.unsloth/llama.cpp/build/bin/libggml.dylib' "
"(mach-o, but wrong architecture)\n"
)
assert "different CPU architecture" in _classify(out, "/m.gguf", "u/x", 1, self._BIN)
def test_bad_cpu_type_never_reaches_dyld_and_is_still_named(self):
out = "/bin/sh: /Users/me/.unsloth/llama.cpp/build/bin/llama-server: Bad CPU type in executable"
msg = _classify(out, "/m.gguf", "u/x", 126, self._BIN)
assert "different CPU architecture" in msg
assert "GGUF file is valid" not in msg
def test_a_linux_exec_failure_is_not_read_as_a_mac_one(self):
out = "bash: /opt/x/llama-server: cannot execute binary file: Exec format error"
msg = _classify(out, "/m.gguf", "u/x", 126, "/opt/x/llama-server")
assert "this Mac" not in msg
class TestHttpCredentialsInTheTail:
def test_a_basic_credential_is_redacted(self):
msg = _classify("Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==", "/m.gguf", "u/x", 1)
assert "QWxhZGRpbg" not in msg
def test_a_bearer_token_is_redacted_including_its_base64_tail(self):
msg = _classify("Authorization: Bearer QUFB+U0VDUkVUL1RBSUw=", "/m.gguf", "u/x", 1)
assert "U0VDUkVU" not in msg
class TestOutputIsNeverTrustedForBeingOurOwnFraming:
"""Child output always gets redaction and the 2000-character cap, even if it echoes our framing."""
_LOG = "/Users/me/.unsloth/studio/logs/llama-server/llama-1-port-8080.log"
@pytest.mark.parametrize(
"prefix",
[
"llama-server output:\n",
"Full log: /wherever\n",
"starting\n\nllama-server output:\n",
"starting\n\nFull log: /wherever\n",
],
)
def test_output_wearing_our_heading_is_still_capped_and_scrubbed(self, prefix, monkeypatch):
monkeypatch.setenv("MY_API_TOKEN", "sk-super-secret-value-1234567890")
out = prefix + "MY_API_TOKEN=sk-super-secret-value-1234567890\n" + "X" * 50000
msg = _classify(out, "/m.gguf", "u/x", 1, None, log_path = self._LOG)
assert "sk-super-secret-value-1234567890" not in msg
assert len(msg) < 3000, len(msg)
assert msg != out
assert self._LOG in msg
def test_repeated_passes_stay_bounded_by_the_tail_cap(self):
cur = "some unrecognised startup noise"
seen = []
for _ in range(60):
cur = _classify(cur, "/m.gguf", "u/x", 1, None, log_path = self._LOG)
seen.append(len(cur))
assert max(seen) < 3000, max(seen)
assert seen[-1] == seen[-2], seen[-4:]
def test_real_output_that_merely_says_the_words_is_still_classified(self):
out = "llama-server output: 3 t/s\nerror while loading shared libraries: libgomp.so.1: cannot open shared object file"
msg = _classify(out, "/m.gguf", "u/x", 1)
assert "libgomp.so.1" in msg
def test_a_dyld_diagnosis_survives_the_heading(self):
out = (
"llama-server output:\n"
"dyld[1]: Library not loaded: @rpath/libllama.dylib\n"
" Reason: tried: '/a/libllama.dylib' (no such file)\n"
)
binary = "/Users/me/.unsloth/llama.cpp/build/bin/llama-server"
assert "libllama.dylib" in _classify(out, "/m.gguf", "u/x", 1, binary)
class TestAnEncodedSecretIsStillRedacted:
"""Redact by secret-looking NAME, since a JSON dump escapes the value so literal matching misses it."""
SECRET = 'pa"ss\\word-12345'
@pytest.fixture(autouse = True)
def _env(self, monkeypatch):
monkeypatch.setenv("DB_PASSWORD", self.SECRET)
monkeypatch.setenv("MY_API_TOKEN", "sk-abcdefghijklmnopqrstuvwxyz")
@pytest.mark.parametrize(
"dump",
[
'{"DB_PASSWORD": "pa\\"ss\\\\word-12345"}',
'DB_PASSWORD=pa"ss\\word-12345',
"DB_PASSWORD='pa\"ss\\word-12345'",
'DB_PASSWORD: pa"ss\\word-12345',
"DB_PASSWORD=pa%22ss%5Cword-12345",
"DB_PASSWORD=secret123456,PORT=8080",
],
)
def test_no_recognisable_fragment_survives(self, dump):
msg = _classify(dump, "/m.gguf", "u/x", 1, None, log_path = "/tmp/l.log")
for fragment in ("ss\\word", "pa%22", "secret123456", 'pa\\"ss'):
assert fragment not in msg, msg
assert "***" in msg
def test_a_value_we_never_set_is_redacted_by_its_name(self):
"""The point of the name pass: we cannot match a value we never saw."""
msg = _classify('{"DB_PASSWORD": "never-set-98765"}', "/m.gguf", "u/x", 1)
assert "never-set-98765" not in msg
@pytest.mark.parametrize(
"line",
[
"PATH=/usr/bin:/bin",
'{"port": 8080}',
"model_path=/models/x.gguf",
"n_ctx: 4096",
"load time = 1234.5 ms",
"llama_model_loader: n_layers = 32",
],
)
def test_ordinary_llama_cpp_output_is_not_redacted(self, line):
"""Over-redaction would destroy the diagnostics this PR exists to add."""
assert "***" not in _classify(line, "/m.gguf", "u/x", 1)
@pytest.mark.parametrize(
"blob",
[
'"A' + '\\"' * 20000 + 'B"',
"K=" + "x" * 100000,
"A=1," * 25000,
'TOKEN="' + "y" * 100000,
],
# Named ids: Windows caps env vars (PYTEST_CURRENT_TEST) at 32767 chars.
ids = ["escaped-quotes", "long-value", "many-pairs", "unterminated-quote"],
)
def test_the_name_pass_stays_linear(self, blob):
"""No nested quantifier: a crafted line must not be able to stall it."""
start = time.monotonic()
_classify(blob, "/m.gguf", "u/x", 1)
assert time.monotonic() - start < 2.0
class TestQuotedShortSecrets:
"""Short secrets in quoted shell or JSON dumps must also be redacted, not only bare NAME=value lines."""
@pytest.mark.parametrize(
"dump",
[
"env dump: DB_PASSWORD=hunter2 PORT=8080",
"env dump: DB_PASSWORD='hunter2'",
'env dump: DB_PASSWORD="hunter2"',
'{"DB_PASSWORD": "hunter2", "port": 8080}',
"DB_PASSWORD: hunter2",
" 'DB_PASSWORD' => 'hunter2'".replace(" => ", ": "),
],
)
def test_the_value_never_reaches_the_message(self, monkeypatch, dump):
monkeypatch.setenv("DB_PASSWORD", "hunter2")
assert "hunter2" not in _classify(dump, "/m.gguf", "u/x", 1)
def test_a_non_secret_short_value_is_still_untouched(self, monkeypatch):
monkeypatch.setenv("UNSLOTH_PORT", "8080")
assert "8080" in _classify('{"UNSLOTH_PORT": "8080"}', "/m.gguf", "u/x", 1)
class TestASecretLongerThanTheTailWindow:
"""Secrets longer than the 8000-char tail window must be matched whole, not sliced before redaction."""
def test_a_long_key_does_not_reach_the_message(self, monkeypatch):
secret = "A" * 12000 + "TAILMARKER"
monkeypatch.setenv("MY_PRIVATE_KEY", secret)
out = "noise " * 100 + "dump: MY_PRIVATE_KEY=" + secret + "\nfatal: boom"
msg = _classify(out, "/m.gguf", "u/x", 1)
assert "TAILMARKER" not in msg
assert "AAAA" not in msg
def test_a_long_minted_api_key_does_not_reach_the_message(self, monkeypatch):
key = "k" * 9000 + "MINTEDMARK"
out = "x" * 5000 + " --api-key " + key + "\nfatal: boom"
msg = _classify(out, "/m.gguf", "u/x", 1, None, secrets = (key,))
assert "MINTEDMARK" not in msg
def test_the_tail_is_still_bounded(self, monkeypatch):
monkeypatch.setenv("MY_PRIVATE_KEY", "A" * 12000)
msg = _classify("z" * 400000 + "\nfatal: boom", "/m.gguf", "u/x", 1)
assert len(msg) < 4000
def test_no_secret_means_the_window_is_unchanged(self, monkeypatch):
for name in list(os.environ):
if "SECRET" in name or "PRIVATE" in name or "PASSWORD" in name:
monkeypatch.delenv(name, raising = False)
assert LlamaCppBackend._max_secret_len(()) >= 0
class TestTheLibraryNameIsBounded:
"""A dyld install name from child output is truncated, so an absurd one cannot bloat the HTTP error."""
def test_an_absurd_install_name_is_truncated(self):
huge = "lib" + "A" * 100000 + ".dylib"
out = (
f"dyld[9]: Library not loaded: @rpath/{huge}\n"
f" Reason: tried: '/a/{huge}' (no such file)\n"
)
msg = _classify(out, "/m.gguf", "u/x", 1, "/i/bin/llama-server")
assert len(msg) < 4000, len(msg)
assert "..." in msg
def test_a_real_install_name_is_untouched(self):
out = (
"dyld[9]: Library not loaded: @rpath/libllama.dylib\n"
" Reason: tried: '/a/libllama.dylib' (no such file)\n"
)
msg = _classify(out, "/m.gguf", "u/x", 1, "/i/bin/llama-server")
assert "libllama.dylib" in msg
assert "..." not in msg
class TestEveryClassifiedBranchIsRedacted:
"""Every classified branch must redact, since a secret in a dyld library name reached the API error."""
def test_a_secret_in_a_dyld_library_name_is_redacted(self, monkeypatch):
token = "sk-supersecret-abcdefghijk"
monkeypatch.setenv("MY_API_TOKEN", token)
out = (
f"dyld[1]: Library not loaded: @rpath/{token}.dylib\n"
f" Reason: tried: '/a/{token}.dylib' (no such file)\n"
)
msg = _classify(
out, "/m.gguf", "u/x", 1, "/i/bin/llama-server", log_path = "/l.log", secrets = (token,)
)
assert token not in msg
assert "***" in msg
def test_a_per_launch_secret_is_redacted_in_a_classified_branch(self):
minted = "unsloth-launch-key-abcdefghij"
out = f"dyld[1]: Library not loaded: @rpath/{minted}.dylib\n"
msg = _classify(out, "/m.gguf", "u/x", 1, "/i/bin/llama-server", secrets = (minted,))
assert minted not in msg
def test_an_ordinary_diagnosis_is_unchanged_by_the_extra_pass(self):
out = (
"dyld[1]: Library not loaded: @rpath/libllama.dylib\n"
" Reason: tried: '/a/libllama.dylib' (no such file)\n"
)
msg = _classify(out, "/m.gguf", "u/x", 1, "/i/bin/llama-server")
assert "libllama.dylib" in msg
assert "***" not in msg
class TestAQuotedValueEndsOnItsOwnDelimiter:
"""A quoted value ends at its own delimiter; an apostrophe or quote inside must not cut it short."""
@pytest.mark.parametrize(
"dump,leak",
[
('{"DB_PASSWORD": "prefix\' supersecret"}', "supersecret"),
("{'DB_PASSWORD': 'has \" quote inside'}", "quote inside"),
('{"DB_PASSWORD": "trailing \'"}', "trailing"),
],
)
def test_the_whole_quoted_value_is_replaced(self, dump, leak):
cleaned = LlamaCppBackend._scrub_secret_values(dump, ())
assert leak not in cleaned, cleaned
assert "***" in cleaned
class TestTheRedactionHolesCodexFound:
"""Three redaction holes: credentials printed as config, not env, slipped past the name-based pass."""
@pytest.mark.parametrize(
"dump",
[
'DB_PASSWORD="prefix supersecret',
"DB_PASSWORD='prefix supersecret",
'DB_PASSWORD="prefix supersecret\nnext=1',
],
)
def test_an_unterminated_quoted_value_is_redacted_to_the_line_end(self, dump):
cleaned = LlamaCppBackend._scrub_secret_values(dump, ())
assert "supersecret" not in cleaned, cleaned
if "\n" in dump:
assert "next=1" in cleaned, "only the value's line should be consumed"
@pytest.mark.parametrize(
"dump,secret",
[
('{"api-key": "abc123def456"}', "abc123def456"),
('{"db-password": "correct horse"}', "correct horse"),
("client.secret: hunter2value", "hunter2value"),
('{"private-key": "MIIEvQIBADAN"}', "MIIEvQIBADAN"),
("auth.token = deadbeefcafe", "deadbeefcafe"),
],
)
def test_a_config_style_key_is_recognised(self, dump, secret):
"""Hyphens and dots spell the same names the predicate underscores."""
assert secret not in LlamaCppBackend._scrub_secret_values(dump, ())
@pytest.mark.parametrize(
"line",
[
"model-path=/models/x.gguf",
"ggml.backend: metal",
"n-gpu-layers=99",
"cache.type-k: q8_0",
"llama_model_loader: n_layers = 32",
"load time = 1234.5 ms",
],
)
def test_a_widened_name_does_not_redact_ordinary_output(self, line):
assert "***" not in LlamaCppBackend._scrub_secret_values(line, ())
@pytest.mark.parametrize(
"order", [("abcdefgh", "abcdefgh VERYSECRET"), ("abcdefgh VERYSECRET", "abcdefgh")]
)
def test_overlapping_secrets_are_replaced_longest_first(self, order):
"""The short one first rewrote the long one so it no longer matched."""
text = "child printed abcdefgh VERYSECRET plainly"
cleaned = LlamaCppBackend._scrub_secret_values(text, order)
assert "VERYSECRET" not in cleaned, cleaned
@pytest.mark.parametrize(
"blob",
['TOKEN="' + "y" * 100000, "a.b.c.d=" * 12000, "A=1," * 25000],
# Named ids for the same Windows env var length limit.
ids = ["unterminated-quote", "dotted-names", "many-pairs"],
)
def test_the_widened_pattern_stays_linear(self, blob):
start = time.monotonic()
LlamaCppBackend._scrub_secret_values(blob, ())
assert time.monotonic() - start < 2.0
class TestRejectedArguments:
"""Argument parsing runs before the model loads, so these are never a bad GGUF or an OOM."""
def test_an_unknown_flag_is_named(self):
msg = _classify("error: invalid argument: --tempp", "/models/x.gguf", "local/x", 1)
assert "--tempp" in msg
assert "extra arguments" in msg
assert "memory" not in msg.lower()
def test_a_flag_unsloth_set_itself_is_covered_by_the_same_message(self):
msg = _classify("error: invalid argument: --flash-attn", "/models/x.gguf", "local/x", 1)
assert "--flash-attn" in msg
assert "reinstall llama.cpp" in msg
def test_a_rejected_value_is_told_apart_from_an_unknown_flag(self):
msg = _classify(
'error while handling argument "--numa": invalid value',
"/models/x.gguf",
"local/x",
1,
)
assert "--numa" in msg
assert "invalid value" in msg
assert "does not recognise" not in msg
def test_a_missing_value_keeps_llama_cpps_own_reason(self):
msg = _classify(
'error while handling argument "--top-k": expected value for argument',
"/models/x.gguf",
"local/x",
1,
)
assert "--top-k" in msg
assert "expected value" in msg
def test_a_std_stoi_failure_is_translated(self):
msg = _classify(
'error while handling argument "--top-k": stoi', "/models/x.gguf", "local/x", 1
)
assert "not a number" in msg
assert "stoi" not in msg
def test_a_value_error_on_a_flag_the_user_did_not_set_stays_neutral(self):
msg = _classify(
'error while handling argument "--flash-attn": invalid value',
"/models/x.gguf",
"local/x",
1,
)
assert "--flash-attn" in msg
assert "reinstall llama.cpp" in msg
def test_a_value_error_on_a_flag_the_user_did_set_names_the_box(self):
msg = LlamaCppBackend._classify_llama_start_failure(
'error while handling argument "--numa": invalid value',
"/models/x.gguf",
"local/x",
1,
None,
None,
(),
["--numa", "wherever"],
)
assert "--numa" in msg
assert "Fix it in the extra arguments" in msg
assert "reinstall" not in msg
def test_an_alias_spelling_falls_back_to_the_neutral_wording(self):
msg = LlamaCppBackend._classify_llama_start_failure(
'error while handling argument "--flash-attn": invalid value',
"/models/x.gguf",
"local/x",
1,
None,
None,
(),
["-fa", "on"],
)
assert "reinstall llama.cpp" in msg
def test_an_ordinary_failure_is_untouched(self):
msg = _classify(_OOM_OUT, "/models/big.gguf", "local/big", 1)
assert "Couldn't allocate memory" in msg
assert "argument" not in msg.lower()
def test_the_argument_scan_reads_only_the_tail(self):
# Asserted by behaviour, not clock: wall-clock budgets on shared CI runners flake.
from core.inference.llama_cpp import _FAILURE_SCAN_TAIL_CHARS
within = "x" * 10_000_000 + "\nerror: invalid argument: --tempp"
assert "--tempp" in _classify(within, "/models/x.gguf", "local/x", 1)
buried = "error: invalid argument: --tempp\n" + "x" * (_FAILURE_SCAN_TAIL_CHARS * 2)
assert "--tempp" not in _classify(buried, "/models/x.gguf", "local/x", 1)
def test_a_model_load_error_mentioning_arguments_is_not_misread(self):
out = "llama_model_load: error loading model: invalid argument (22)"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "does not recognise" not in msg
class TestArgumentErrorsAreQuotedShort:
"""What a failed start copies out of the child's own output."""
def test_a_pathological_argument_is_truncated(self):
out = "error: invalid argument: " + "x" * 50_000
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert len(msg) < 1_000, len(msg)
assert "..." in msg
assert "does not recognise the argument" in msg
assert "xxxx" in msg
def test_a_pathological_reason_is_truncated(self):
out = 'error while handling argument "--top-k": ' + "y" * 50_000
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert len(msg) < 1_000, len(msg)
assert "--top-k" in msg
def test_an_ordinary_argument_error_is_untouched(self):
out = "error: invalid argument: --tempp"
msg = _classify(out, "/models/x.gguf", "local/x", 1)
assert "--tempp" in msg
assert "..." not in msg
class TestTensorSplitQuantizedKvUnsupported:
"""Quantized KV with --split-mode tensor is refused by older llama.cpp; name that remedy, not OOM."""
_OUT = (
"llama_init_from_model: simultaneous use of SPLIT_MODE_TENSOR and "
"KV cache quantization not implemented\n"
)
def test_the_legacy_refusal_names_the_build_and_the_remedies(self):
msg = _classify(self._OUT, "/models/x.gguf", "local/x", 2)
assert "b9455" in msg
assert "quantized KV cache" in msg
assert "Update" in msg
assert "f16" in msg
assert "Tensor Parallelism" in msg
assert "GGUF file is valid" not in msg
def test_it_does_not_shadow_the_architecture_gate(self):
"""A different, permanent, per-model limit with its own remedy."""
out = "llama_init_from_model: split_mode_tensor not implemented for this arch\n"
msg = _classify(out, "/models/x.gguf", "local/x", 2)
assert "architecture" in msg
assert "b9455" not in msg
def test_the_marker_is_matched_case_insensitively(self):
"""llama.cpp prints SPLIT_MODE_TENSOR upper-case; the classifier lowers."""
assert LlamaCppBackend._is_tensor_quant_kv_unsupported(self._OUT)
assert LlamaCppBackend._is_tensor_quant_kv_unsupported(self._OUT.lower())
assert not LlamaCppBackend._is_tensor_quant_kv_unsupported("")
assert not LlamaCppBackend._is_tensor_quant_kv_unsupported(
"split_mode_tensor not implemented"
)
def test_a_hard_crash_carrying_it_is_not_retried_as_a_projector_fault(self):
"""Without the marker a doomed tensor load would also pay the text-only vision retry."""
assert LlamaCppBackend._output_has_nonprojector_diagnostic(self._OUT)
def test_it_is_not_the_signal_crash_the_split_axis_latch_requires(self):
"""LLAMA_LOG_ERROR exits 1 with no signal, so it needs its own path, not issue 6415."""
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