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: show the Hub error for an unreadable GGUF repo instead of routing it to Transformers (#12117)
Daniel Han3ab8cc6265d7
diff --git a/studio/backend/tests/test_gguf_hub_unreadable.py b/studio/backend/tests/test_gguf_hub_unreadable.pynew file mode 100644index 00000000000..76961448547--- /dev/null+++ b/studio/backend/tests/test_gguf_hub_unreadable.py@@ -0,0 +1,241 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""A GGUF repo whose Hub listing cannot be read must not be routed to Transformers (#11551)."""++from pathlib import Path+from types import SimpleNamespace++import huggingface_hub+import pytest++import core.inference.llama_cpp as llama_cpp+import utils.hf_cache_settings as hf_cache_settings+import utils.models.model_config as mc+from utils.models.model_config import (+ GgufRepoUnreadableError,+ GgufVariantInfo,+ ModelConfig,+ _looks_like_gguf_repo,+ detect_gguf_model_remote,+)++REPO = "unsloth/LFM2.5-VL-1.6B-GGUF"+GGUF = "LFM2.5-VL-1.6B-UD-Q4_K_XL.gguf"+++class RepositoryNotFoundError(Exception):+ """Matched by type name, as detect_gguf_model_remote does."""++ def __init__(+ self,+ message,+ status_code = 401,+ ):+ super().__init__(message)+ self.response = SimpleNamespace(status_code = status_code)++[email protected](autouse = True)+def _isolated(tmp_path, monkeypatch):+ monkeypatch.delenv("HF_HUB_OFFLINE", raising = False)+ monkeypatch.delenv("TRANSFORMERS_OFFLINE", raising = False)+ monkeypatch.setattr(+ hf_cache_settings, "get_hf_cache_paths", lambda: SimpleNamespace(hub_cache = tmp_path)+ )+ monkeypatch.setattr(mc.time, "sleep", lambda *_: None)+ monkeypatch.setattr(+ llama_cpp.LlamaCppBackend,+ "_find_llama_server_binary",+ staticmethod(lambda *, include_denied = False: "/fake/llama-server"),+ )+ monkeypatch.setattr(llama_cpp, "cached_gguf_for_load", lambda repo, variant, **kwargs: None)+ monkeypatch.setattr(+ mc,+ "list_gguf_variants",+ lambda identifier, hf_token = None: (+ [GgufVariantInfo(filename = GGUF, quant = "UD-Q4_K_XL", size_bytes = 1)],+ True,+ ),+ )+ monkeypatch.setattr(mc, "is_vision_model", lambda *a, **k: False)+ monkeypatch.setattr(mc, "detect_audio_type", lambda *a, **k: None)+ monkeypatch.setattr(mc, "is_model_cached", lambda *a, **k: False)+ return tmp_path+++def _hub(behaviour):+ def model_info(repo_id, **kwargs):+ if isinstance(behaviour, BaseException):+ raise behaviour+ return SimpleNamespace(siblings = [SimpleNamespace(rfilename = f) for f in behaviour])++ return model_info+++def _cache(root: Path, repo: str, name: str) -> None:+ snapshot = root / f"models--{repo.replace('/', '--')}" / "snapshots" / ("a" * 40)+ snapshot.mkdir(parents = True, exist_ok = True)+ (snapshot / name).write_bytes(b"cached")+++def test_healthy_hub_still_detects_gguf(monkeypatch):+ monkeypatch.setattr(huggingface_hub, "model_info", _hub([GGUF, "README.md"]))+ config = ModelConfig.from_identifier(REPO)+ assert config.is_gguf and config.gguf_hf_repo == REPO+ assert config.is_vision+++def test_hub_401_on_gguf_repo_raises_clear_error(monkeypatch):+ monkeypatch.setattr(+ huggingface_hub, "model_info", _hub(RepositoryNotFoundError("401 Client Error"))+ )+ with pytest.raises(GgufRepoUnreadableError) as exc_info:+ ModelConfig.from_identifier(REPO)+ msg = str(exc_info.value)+ assert REPO in msg+ assert "RepositoryNotFoundError, HTTP 401" in msg+ assert "token in Settings" in msg and "HF_ENDPOINT" in msg+ assert "AutoConfig" not in msg+ assert isinstance(exc_info.value, ValueError)+++def test_hub_401_is_not_served_from_a_stale_cache(monkeypatch, _isolated):+ _cache(_isolated, REPO, GGUF)+ monkeypatch.setattr(+ huggingface_hub, "model_info", _hub(RepositoryNotFoundError("401 Client Error"))+ )+ with pytest.raises(GgufRepoUnreadableError):+ ModelConfig.from_identifier(REPO)+++def test_repeated_timeouts_on_uncached_gguf_repo_raise_clear_error(monkeypatch):+ monkeypatch.setattr(huggingface_hub, "model_info", _hub(TimeoutError("read timed out")))+ with pytest.raises(GgufRepoUnreadableError, match = "TimeoutError: read timed out"):+ ModelConfig.from_identifier(REPO)+++def test_repeated_timeouts_with_cached_snapshot_still_load_from_cache(monkeypatch, _isolated):+ _cache(_isolated, REPO, GGUF)+ monkeypatch.setattr(huggingface_hub, "model_info", _hub(TimeoutError("read timed out")))+ config = ModelConfig.from_identifier(REPO)+ assert config.is_gguf+++def test_explicit_variant_marks_an_unsuffixed_repo_as_gguf(monkeypatch):+ monkeypatch.setattr(huggingface_hub, "model_info", _hub(OSError("proxy refused")))+ with pytest.raises(GgufRepoUnreadableError, match = "OSError: proxy refused"):+ ModelConfig.from_identifier("org/some-model", gguf_variant = "Q4_K_M")+++def test_offline_uncached_gguf_repo_raises_clear_error(monkeypatch):+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")+ monkeypatch.setattr(huggingface_hub, "model_info", _hub(AssertionError("no API offline")))+ with pytest.raises(GgufRepoUnreadableError, match = "offline"):+ ModelConfig.from_identifier(REPO)+++ "failure", [RepositoryNotFoundError("401 Client Error"), TimeoutError("read timed out")]+)+def test_non_gguf_repo_with_hub_failure_keeps_todays_behaviour(monkeypatch, failure):+ monkeypatch.setattr(huggingface_hub, "model_info", _hub(failure))+ config = ModelConfig.from_identifier("unsloth/Qwen3-0.6B")+ assert config is not None and not config.is_gguf+++def test_gguf_repo_without_gguf_files_keeps_todays_behaviour(monkeypatch):+ monkeypatch.setattr(huggingface_hub, "model_info", _hub(["config.json", "model.safetensors"]))+ config = ModelConfig.from_identifier("org/odd-GGUF")+ assert config is not None and not config.is_gguf+++def test_public_detect_signature_unchanged_outside_from_identifier(monkeypatch):+ monkeypatch.setattr(+ huggingface_hub, "model_info", _hub(RepositoryNotFoundError("401 Client Error"))+ )+ assert detect_gguf_model_remote(REPO) is None+++ "repo_id,expected",+ [+ ("unsloth/LFM2.5-VL-1.6B-GGUF", True),+ ("prism-ml/Ternary-Bonsai-27B-gguf", True),+ ("org/gguf-models", True),+ ("org/model_GGUF.v2", True),+ ("unsloth/Qwen3-0.6B", False),+ ("org/ggufmaker", False),+ ("gguf-org/regular-model", False),+ ],+)+def test_looks_like_gguf_repo(repo_id, expected):+ assert _looks_like_gguf_repo(repo_id) is expected+++def test_variant_for_a_cached_transformers_repo_still_reaches_transformers(monkeypatch, _isolated):+ _cache(_isolated, "org/some-model", "config.json")+ monkeypatch.setattr(huggingface_hub, "model_info", _hub(OSError("proxy refused")))+ config = ModelConfig.from_identifier("org/some-model", gguf_variant = "Q4_K_M")+ assert config is not None and not config.is_gguf+++def test_slow_link_recovers_on_a_longer_bound(monkeypatch):+ timeouts = []++ def model_info(repo_id, **kwargs):+ timeouts.append(kwargs.get("timeout"))+ if len(timeouts) == 1:+ raise TimeoutError("read timed out")+ return SimpleNamespace(siblings = [SimpleNamespace(rfilename = GGUF)])++ monkeypatch.setattr(huggingface_hub, "model_info", model_info)+ config = ModelConfig.from_identifier(REPO)+ assert config.is_gguf+ assert timeouts[:2] == [15.0, 30.0]+++def test_listing_bounds_escalate_and_a_refusal_is_not_retried(monkeypatch):+ timeouts = []++ def timing_out(repo_id, **kwargs):+ timeouts.append(kwargs.get("timeout"))+ raise TimeoutError("read timed out")++ monkeypatch.setattr(huggingface_hub, "model_info", timing_out)+ assert detect_gguf_model_remote(REPO) is None+ assert timeouts == [15.0, 30.0, 60.0]++ timeouts.clear()+ with pytest.raises(TimeoutError):+ mc._hub_model_info_slow_link(REPO)+ assert timeouts == [15.0, 30.0, 60.0]++ calls = []++ def refused(repo_id, **kwargs):+ calls.append(kwargs.get("timeout"))+ raise RepositoryNotFoundError("401 Client Error")++ monkeypatch.setattr(huggingface_hub, "model_info", refused)+ with pytest.raises(RepositoryNotFoundError):+ mc._hub_model_info_slow_link(REPO)+ assert calls == [15.0]+++def test_gguf_named_repo_with_a_cached_config_keeps_the_transformers_route(monkeypatch, _isolated):+ _cache(_isolated, REPO, "config.json")+ monkeypatch.setattr(huggingface_hub, "model_info", _hub(TimeoutError("read timed out")))+ config = ModelConfig.from_identifier(REPO)+ assert config is not None and not config.is_gguf++[email protected]("partial", ["mmproj-F16.gguf", "README.md"])+def test_offline_partial_snapshot_without_a_main_gguf_raises_clear_error(+ monkeypatch, _isolated, partial+):+ _cache(_isolated, REPO, partial)+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")+ monkeypatch.setattr(huggingface_hub, "model_info", _hub(AssertionError("no API offline")))+ with pytest.raises(GgufRepoUnreadableError, match = "offline"):+ ModelConfig.from_identifier(REPO)diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.pyindex 81fce22219b..17b25dc70c4 100644--- a/studio/backend/tests/test_openai_auto_switch.py+++ b/studio/backend/tests/test_openai_auto_switch.py@@ -11718,6 +11718,12 @@ def test_a_stale_idle_reload_stash_diverts_a_refusal_into_a_reload(monkeypatch):)(),)kw._last_unloaded_model = ("unsloth/Idle-GGUF", "Q4_K_M", "unsloth/Idle-GGUF")+ # Fictional repo, blocked Hub: answer "no GGUF" so resolution still reaches the double (#11551).+ import utils.models.model_config as model_config++ monkeypatch.setattr(+ model_config, "detect_gguf_model_remote", lambda identifier, hf_token = None: None+ )with pytest.raises(Exception):asyncio.run(diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.pyindex 443b93cdbcf..083775073fe 100644--- a/studio/backend/utils/models/model_config.py+++ b/studio/backend/utils/models/model_config.py@@ -1161,6 +1161,8 @@ _hub_model_info_scope: ContextVar[Optional[_HubModelInfoScope]] = ContextVar(# Bound the Hub lookup so a DNS-dead session fails fast to the cache instead of hanging on retries._HUB_MODEL_INFO_TIMEOUT = 15.0+# Unbounded before #10230; three identical 15s reads never pass on a slow link (#11551).+_GGUF_LISTING_TIMEOUTS = (_HUB_MODEL_INFO_TIMEOUT, 30.0, 60.0)@_contextlib.contextmanager@@ -1206,6 +1208,29 @@ def _hub_model_info(return info+def _is_timeout_error(exc: BaseException) -> bool:+ if isinstance(exc, TimeoutError):+ return True+ return any("Timeout" in cls.__name__ for cls in type(exc).__mro__)+++def _hub_model_info_slow_link(+ repo_id: str,+ hf_token: HfTokenArg = None,+ *,+ files_metadata: bool = False,+):+ """Re-read with a longer bound only after a timeout; a refusal fails on the first attempt."""+ for attempt, timeout in enumerate(_GGUF_LISTING_TIMEOUTS):+ try:+ return _hub_model_info(+ repo_id, hf_token, files_metadata = files_metadata, timeout = timeout+ )+ except Exception as e:+ if attempt == len(_GGUF_LISTING_TIMEOUTS) - 1 or not _is_timeout_error(e):+ raise++# Revision-less entries keep the historical 3-part key; pinned entries append revision._CapabilityCacheKey = Tuple[Any, ...]_vision_detection_cache: Dict[_CapabilityCacheKey, bool] = {}@@ -3053,7 +3078,7 @@ def list_gguf_variants(return cached if cached is not None else ([], False)try:- info = _hub_model_info(repo_id, hf_token, files_metadata = True)+ info = _hub_model_info_slow_link(repo_id, hf_token, files_metadata = True)except Exception as e:# Permanent errors (deleted/gated/bad revision) must surface; stale cache would mask the# real cause. Matches the early return in ``detect_gguf_model_remote``.@@ -3338,20 +3363,74 @@ def _detect_gguf_from_hf_cache(repo_id: str) -> Optional[str]:return None+class GgufRepoUnreadableError(ValueError):+ """A ValueError so /load and /validate answer 400 with its text (#11551)."""+++# from_identifier's sink for the Hub error behind a detect_gguf_model_remote None.+_gguf_remote_detect_failure: ContextVar[Optional[List[Exception]]] = ContextVar(+ "gguf_remote_detect_failure", default = None+)+++def _note_gguf_remote_detect_failure(error: Exception) -> None:+ sink = _gguf_remote_detect_failure.get()+ if sink is not None:+ sink.append(error)+++_GGUF_REPO_NAME_RE = _re.compile(r"(?:^|[-_.])gguf(?:$|[-_.])", _re.IGNORECASE)+++def _looks_like_gguf_repo(repo_id: str, gguf_variant: Optional[str] = None) -> bool:+ # A cached Transformers, diffusers or adapter checkpoint can still load from that cache.+ if any(+ (snap / name).is_file()+ for snap in _iter_hf_cache_snapshots(repo_id)+ for name in ("config.json", "model_index.json", "adapter_config.json")+ ):+ return False+ return bool(gguf_variant) or bool(+ _GGUF_REPO_NAME_RE.search(repo_id.rstrip("/").rsplit("/", 1)[-1])+ )+++def _gguf_repo_unreadable_message(repo_id: str, error: Optional[Exception]) -> str:+ if error is None:+ return (+ f"Could not load the GGUF repo '{repo_id}': Studio is offline and the repo is not "+ "in the local cache. Connect to the internet once to download it, then try again."+ )+ status = getattr(getattr(error, "response", None), "status_code", None)+ first_line = (str(error).strip().splitlines() or [""])[0][:200]+ cause = type(error).__name__+ if status is not None:+ cause += f", HTTP {status}"+ if first_line:+ cause += f": {first_line}"+ return (+ f"Could not read the GGUF repo '{repo_id}' from Hugging Face ({cause}). "+ "Unsloth needs the repo's file list to pick a GGUF file. Check the Hugging Face "+ "token in Settings (clear it if it is expired or revoked), your network, proxy "+ "or HF_ENDPOINT, then try again."+ )++def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Optional[str]:"""Return the best GGUF filename in a HF repo, or None.- Retries (3 attempts, 1s/2s/4s backoff) on transient HF Hub failures: a+ Retries (3 attempts bounded 15s/30s/60s, 1s/2s backoff) on transient HF Hub failures: asilent None would make the caller treat a GGUF-only repo as non-GGUF andfall through to MLX on Apple Silicon. Offline falls back to the local cache.+ A None from a failed Hub read is also reported to ``_gguf_remote_detect_failure``."""if _env_offline():return _detect_gguf_from_hf_cache(repo_id)last_err: Optional[Exception] = None- for attempt in range(3):+ for attempt, timeout in enumerate(_GGUF_LISTING_TIMEOUTS):try:- info = _hub_model_info(repo_id, hf_token)+ info = _hub_model_info(repo_id, hf_token, timeout = timeout)repo_files = []for sibling in info.siblings:fname = sibling.rfilename@@ -3378,6 +3457,7 @@ def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Op"EntryNotFoundError",):logger.debug(f"Could not check GGUF files for '{repo_id}': {e}")+ _note_gguf_remote_detect_failure(e)return Noneif attempt < 2:time.sleep(2**attempt)@@ -3393,6 +3473,8 @@ def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Opreturn cachedlogger.warning(f"Could not check GGUF files for '{repo_id}' after 3 attempts: {last_err}")+ if last_err is not None:+ _note_gguf_remote_detect_failure(last_err)return None@@ -4269,7 +4351,20 @@ class ModelConfig:)else:# Does the HF repo contain GGUF files?- gguf_filename = detect_gguf_model_remote(identifier, hf_token = hf_token)+ detect_failures: List[Exception] = []+ failure_token = _gguf_remote_detect_failure.set(detect_failures)+ try:+ gguf_filename = detect_gguf_model_remote(identifier, hf_token = hf_token)+ finally:+ _gguf_remote_detect_failure.reset(failure_token)+ # A failed listing is not "no GGUF"; a refused repo is never served from cache (#11551).+ if not gguf_filename and _looks_like_gguf_repo(identifier, gguf_variant):+ if detect_failures:+ raise GgufRepoUnreadableError(+ _gguf_repo_unreadable_message(identifier, detect_failures[-1])+ ) from None+ if _env_offline():+ raise GgufRepoUnreadableError(_gguf_repo_unreadable_message(identifier, None))if gguf_filename:# Preflight: verify the llama-server binary exists before a multi-GB download.# include_denied: a transiently locked binary still exists and the lock clears in time.