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: keep GGUF variant listings off the default thread pool so a stalled Hub cannot block downloaded models (#14134)

Daniel Han336590e7ff67
diff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.py
index fe2b49558f6..60e729947e2 100644
--- a/studio/backend/hub/services/models/gguf_variants.py
+++ b/studio/backend/hub/services/models/gguf_variants.py
@@ -8,6 +8,8 @@ from __future__ import annotations
from hub.services.models import account_access
import asyncio
+import contextvars
+import functools
import hashlib
import json
import re
@@ -15,6 +17,7 @@ import threading
import time
import weakref
from collections import OrderedDict
+from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
from typing import NamedTuple, Optional
@@ -1033,8 +1036,24 @@ def _complete_with_servable(snapshot: str, complete, variants):
# running, and 23 retries filled all 20 default-executor workers.
_VARIANTS_INFLIGHT: "weakref.WeakKeyDictionary" = weakref.WeakKeyDictionary()
+# Not the default executor: a stalled Hub holds a remote listing's thread until it answers, and enough
+# of them blocked every asyncio.to_thread caller (load, chat) and the On Device disk-only listing (#14038).
+_HUB_LISTING_POOL = ThreadPoolExecutor(thread_name_prefix = "gguf-hub-listing")
+_DISK_LISTING_POOL = ThreadPoolExecutor(thread_name_prefix = "gguf-disk-listing")
-async def _shared_variants_scan(key: tuple, compute):
+
+async def listing_thread(offline: bool, fn, /, *args, **kwargs):
+ """``asyncio.to_thread`` on the listing pool for *offline* (context variables carried along)."""
+ loop = asyncio.get_running_loop()
+ call = functools.partial(contextvars.copy_context().run, fn, *args, **kwargs)
+ return await loop.run_in_executor(_DISK_LISTING_POOL if offline else _HUB_LISTING_POOL, call)
+
+
+async def _shared_variants_scan(
+ key: tuple,
+ compute,
+ offline: bool = False,
+):
"""*compute* in a thread, shared with any identical request already running."""
loop = asyncio.get_running_loop()
inflight = _VARIANTS_INFLIGHT.get(loop)
@@ -1044,7 +1063,7 @@ async def _shared_variants_scan(key: tuple, compute):
task = inflight.get(key)
if task is None:
- task = asyncio.ensure_future(asyncio.to_thread(compute))
+ task = asyncio.ensure_future(listing_thread(offline, compute))
def _release(finished: asyncio.Future) -> None:
inflight.pop(key, None)
@@ -1096,11 +1115,11 @@ async def _audio_cpp_variants_answer(
return None
real_repo = audio_cpp_models.repo_of(text) or text
if account_access.managed_account():
- await asyncio.to_thread(account_access.require_model_access, real_repo)
+ await listing_thread(False, account_access.require_model_access, real_repo)
network = not (offline or audio_cpp_models.hub_offline())
try:
- model = await asyncio.to_thread(
- audio_cpp_models.resolve, text, None, hf_token, network = network
+ model = await listing_thread(
+ not network, audio_cpp_models.resolve, text, None, hf_token, network = network
)
except Exception as exc: # noqa: BLE001 - the generic lister reports an unreadable repo
logger.debug("audio.cpp variants for %s unavailable: %s", text, exc)
@@ -1200,7 +1219,7 @@ async def _audio_cpp_variants_answer(
)
return rows
- details = await asyncio.to_thread(_details)
+ details = await listing_thread(not network, _details)
loadable = [row.quant for row in details if row.downloaded]
return VariantsAnswer(
GgufVariantsResponse(
@@ -1327,7 +1346,7 @@ async def _mlx_precision_variants_answer(
variant_format = "mlx",
)
- response = await asyncio.to_thread(_listing)
+ response = await listing_thread(offline, _listing)
if response is None:
return None
return VariantsAnswer(response, None, cache_authorized = False)
@@ -1352,8 +1371,8 @@ async def get_gguf_variants_answer(
access_options = {"offline": True} if offline else {}
if local_path:
if account_access.managed_account():
- await asyncio.to_thread(
- account_access.require_model_access, local_path, **access_options
+ await listing_thread(
+ offline, account_access.require_model_access, local_path, **access_options
)
hf_token = account_access.account_hf_token(hf_token)
from core.inference.audio_cpp_models import is_umbrella_id
@@ -1365,7 +1384,9 @@ async def get_gguf_variants_answer(
return audio_cpp_answer
if account_access.managed_account():
try:
- await asyncio.to_thread(account_access.require_model_access, repo_id, **access_options)
+ await listing_thread(
+ offline, account_access.require_model_access, repo_id, **access_options
+ )
except HTTPException:
# No grant exists before the first download, so for a private repo the caller's own
# token proves Hub access instead. Offline requests need an existing grant or public proof.
@@ -1373,7 +1394,9 @@ async def get_gguf_variants_answer(
raise
if is_local_path(repo_id) or not _is_valid_repo_id(repo_id):
raise
- await asyncio.to_thread(account_access.authorize_download, repo_id, "model", hf_token)
+ await listing_thread(
+ False, account_access.authorize_download, repo_id, "model", hf_token
+ )
# Returned with the listing because the HF cache answers before local_path, so a caller cannot infer
# the copy from the request alone.
answered_from: list[Optional[str]] = [None]
@@ -2549,7 +2572,9 @@ async def get_gguf_variants_answer(
configured_cache_key(),
)
try:
- answer = await _shared_variants_scan(inflight_key, _compute_with_cleanables)
+ answer = await _shared_variants_scan(
+ inflight_key, _compute_with_cleanables, offline = bool(offline)
+ )
# Only after an empty GGUF listing, so GGUF answers never change.
if not answer.response.variants and not local_path:
mlx_answer = await _mlx_precision_variants_answer(
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index b2747be898b..b0779d889a5 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -4757,13 +4757,17 @@ async def get_gguf_variants(
# it is the only name an API-key caller has for a local GGUF (see the /hub twin).
repo_id = resolve_host_path_reference(repo_id) or repo_id
local_path = resolve_host_path_reference(local_path) or local_path
+ from hub.services.models import gguf_variants as hub_gguf_variants
+
if account_access.managed_account():
- await asyncio.to_thread(
- account_access.require_model_access, repo_id, **({"offline": True} if offline else {})
+ await hub_gguf_variants.listing_thread(
+ offline,
+ account_access.require_model_access,
+ repo_id,
+ **({"offline": True} if offline else {}),
)
try:
hf_token = _resolve_hub_token(hf_token_header, hf_token)
- from hub.services.models import gguf_variants as hub_gguf_variants
answer = await hub_gguf_variants.get_gguf_variants_answer(
repo_id,
diff --git a/studio/backend/tests/test_gguf_listing_threads.py b/studio/backend/tests/test_gguf_listing_threads.py
new file mode 100644
index 00000000000..2943f1cace9
--- /dev/null
+++ b/studio/backend/tests/test_gguf_listing_threads.py
@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""GGUF variant listings stay off the default executor (#14038).
+
+A stalled Hub holds a remote listing's thread until it answers. On the shared default executor
+enough of them blocked every ``asyncio.to_thread`` caller, and the On Device picker's disk-only
+listing of a downloaded repo timed out behind them.
+"""
+
+import asyncio
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from types import SimpleNamespace
+
+from hub.services.models import gguf_variants
+
+
+def _cached_repo(root, repo_id, quants):
+ # Plain files, not blob symlinks: the layout huggingface_hub writes where symlinks are unavailable (Windows).
+ repo_dir = root / f"models--{repo_id.replace('/', '--')}"
+ sha = "a" * 40
+ snapshot = repo_dir / "snapshots" / sha
+ snapshot.mkdir(parents = True)
+ (repo_dir / "refs").mkdir()
+ (repo_dir / "refs" / "main").write_text(sha)
+ leaf = repo_id.split("/")[1].removesuffix("-GGUF")
+ for i, quant in enumerate(quants):
+ (snapshot / f"{leaf}-{quant}.gguf").write_bytes(b"GGUF" + bytes([i]) * 4096)
+
+
+def _pin_cache_roots(monkeypatch, active, home):
+ monkeypatch.setattr(
+ "utils.hf_cache_settings.get_hf_cache_paths",
+ lambda: SimpleNamespace(hub_cache = active, hf_home = home, source = "studio", cache_home = home),
+ )
+ monkeypatch.setattr("hub.utils.hf_cache_state.hf_cache_roots", lambda **kw: [active])
+ monkeypatch.setattr(
+ "hub.utils.hf_cache_state.hf_cache_root",
+ lambda create = False, root = None, **kw: root if root is not None else active,
+ )
+
+
+async def _with_saturated_default_executor(body):
+ """Run *body* while the loop's only default-executor worker is held, as stalled Hub calls do."""
+ loop = asyncio.get_running_loop()
+ loop.set_default_executor(ThreadPoolExecutor(max_workers = 1))
+ gate = threading.Event()
+ holder = asyncio.ensure_future(asyncio.to_thread(gate.wait, 30))
+ await asyncio.sleep(0.05)
+ try:
+ return await body()
+ finally:
+ gate.set()
+ await holder
+
+
+def test_disk_only_listing_answers_while_the_default_executor_is_saturated(monkeypatch, tmp_path):
+ hub = tmp_path / "hub"
+ _cached_repo(hub, "unsloth/Qwen3.8-27B-GGUF", ["UD-Q4_K_XL", "Q8_0"])
+ _pin_cache_roots(monkeypatch, hub, tmp_path)
+
+ async def listing():
+ answer = await asyncio.wait_for(
+ gguf_variants.get_gguf_variants_answer(
+ "unsloth/Qwen3.8-27B-GGUF",
+ prefer_local_cache = True,
+ offline = True,
+ include_cache_locations = True,
+ ),
+ 10,
+ )
+ return answer.response
+
+ response = asyncio.run(_with_saturated_default_executor(listing))
+ assert sorted(v.quant for v in response.variants) == ["Q8_0", "UD-Q4_K_XL"]
+ assert all(v.downloaded for v in response.variants)
+
+
+def test_a_stalled_hub_listing_leaves_the_default_executor_free():
+ async def body():
+ loop = asyncio.get_running_loop()
+ loop.set_default_executor(ThreadPoolExecutor(max_workers = 1))
+ gate = threading.Event()
+ stalled = asyncio.ensure_future(
+ gguf_variants._shared_variants_scan(("stalled-hub-listing",), lambda: gate.wait(30))
+ )
+ await asyncio.sleep(0.05)
+ try:
+ # What model load, chat and every other to_thread caller need.
+ return await asyncio.wait_for(asyncio.to_thread(lambda: "free"), 10)
+ finally:
+ gate.set()
+ await stalled
+
+ assert asyncio.run(body()) == "free"
+
+
+def test_a_disk_only_listing_does_not_queue_behind_stalled_hub_listings(monkeypatch):
+ monkeypatch.setattr(gguf_variants, "_HUB_LISTING_POOL", ThreadPoolExecutor(max_workers = 1))
+
+ async def body():
+ gate = threading.Event()
+ stalled = asyncio.ensure_future(
+ gguf_variants._shared_variants_scan(("hub",), lambda: gate.wait(30))
+ )
+ await asyncio.sleep(0.05)
+ try:
+ return await asyncio.wait_for(
+ gguf_variants._shared_variants_scan(("disk",), lambda: "disk", offline = True), 10
+ )
+ finally:
+ gate.set()
+ await stalled
+
+ assert asyncio.run(body()) == "disk"
+
+
+def test_listing_threads_carry_context_variables():
+ import contextvars
+
+ marker = contextvars.ContextVar("marker", default = None)
+
+ async def body():
+ marker.set("request")
+ return await gguf_variants.listing_thread(True, marker.get)
+
+ assert asyncio.run(body()) == "request"
+
+
+def test_a_stalled_managed_account_preflight_leaves_the_default_executor_free(monkeypatch):
+ # For an ungranted repo the preflight asks the Hub, so it stalls with it.
+ gate = threading.Event()
+ monkeypatch.setattr(gguf_variants.account_access, "managed_account", lambda: True)
+ monkeypatch.setattr(
+ gguf_variants.account_access, "require_model_access", lambda *a, **k: gate.wait(30)
+ )
+
+ async def body():
+ loop = asyncio.get_running_loop()
+ loop.set_default_executor(ThreadPoolExecutor(max_workers = 1))
+ listing = asyncio.ensure_future(
+ gguf_variants.get_gguf_variants_answer("unsloth/Stalled-GGUF", local_path = "/x")
+ )
+ await asyncio.sleep(0.05)
+ try:
+ return await asyncio.wait_for(asyncio.to_thread(lambda: "free"), 10)
+ finally:
+ gate.set()
+ listing.cancel()
+
+ assert asyncio.run(body()) == "free"
diff --git a/studio/backend/tests/test_mlx_precision_variants.py b/studio/backend/tests/test_mlx_precision_variants.py
index 6086d5cc7f1..06f3f27de45 100644
--- a/studio/backend/tests/test_mlx_precision_variants.py
+++ b/studio/backend/tests/test_mlx_precision_variants.py
@@ -140,7 +140,11 @@ def _no_gguf_rows(monkeypatch, cache_authorized = True):
gguf_variants.GgufVariantsResponse(repo_id = _REPO), None, cache_authorized
)
- async def _scan(key, compute):
+ async def _scan(
+ key,
+ compute,
+ offline = False,
+ ):
return empty
monkeypatch.setattr(gguf_variants, "_shared_variants_scan", _scan)
@@ -182,7 +186,11 @@ def test_gguf_listing_is_answered_without_asking_for_mlx_folders(monkeypatch):
gguf_variants.GgufVariantsResponse(repo_id = "a/b-GGUF", variants = [row]), None
)
- async def _scan(key, compute):
+ async def _scan(
+ key,
+ compute,
+ offline = False,
+ ):
return gguf
class _NoHub: