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.

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.py
new file mode 100644
index 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.py
index 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.py
index 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: a
silent None would make the caller treat a GGUF-only repo as non-GGUF and
fall 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 None
if attempt < 2:
time.sleep(2**attempt)
@@ -3393,6 +3473,8 @@ def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Op
return cached
logger.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.