unslothai/unsloth · error · RuntimeError

Download stalled for '{model_name}' even with HF_HUB_DISABLE

Error message

Download stalled for '{model_name}' even with HF_HUB_DISABLE_XET=1 -- check your network connection

What it means

Terminal failure of the model-download retry ladder: the worker reported a 'stall' response, the orchestrator already retried once with HF_HUB_DISABLE_XET=1 (or Xet was already disabled), and the second attempt stalled too. The subprocess is shut down and the load is abandoned; the message points at the network as the differentiator between the two failing transports.

Source

Thrown at studio/backend/core/inference/orchestrator.py:1417

                    self.active_model_name = None
                    self.models.clear()
                    return False

                try:
                    resp = self._wait_response("loaded")
                except DownloadStallError:
                    # First stall with Xet on -> retry with Xet disabled
                    if attempt == 0 and not disable_xet:
                        logger.warning(
                            "Download stalled for '%s' -- retrying with HF_HUB_DISABLE_XET=1",
                            model_name,
                        )
                        self._shutdown_subprocess(timeout = 5)
                        disable_xet = True
                        continue
                    # Second stall (or xet already off) -> give up
                    self._shutdown_subprocess(timeout = 5)
                    raise RuntimeError(
                        f"Download stalled for '{model_name}' even with "
                        f"HF_HUB_DISABLE_XET=1 -- check your network connection"
                    )

                if resp.get("success"):
                    # A cancel can land while we were parked in _wait_response above.
                    # cancel_load (off the lifecycle gate) discards this model's loading
                    # marker BEFORE its teardown, so a Stop-loading that fired after the
                    # worker queued "loaded" (which we can still consume during cancel_load's
                    # shutdown window) shows up here only as the marker's removal. Without
                    # this recheck we would publish active_model_name/models for a model
                    # /unload reported cancelled, over a subprocess cancel_load just killed;
                    # its post-teardown re-clear cannot undo a publish that lands after it
                    # returns. Observe the removal and abort; cancel_load owns teardown.
                    if model_name not in self.loading_models:
                        logger.info(
                            "Load for '%s' was cancelled while waiting for 'loaded'; "
                            "not publishing the cancelled model",

View on GitHub (pinned to 203007d190)

Solutions

1. Verify basic connectivity: curl -I https://huggingface.co and try downloading the repo with huggingface-cli.
2. If behind a proxy, set HTTPS_PROXY correctly and confirm it supports large streaming responses.
3. Pre-download the model outside the app (huggingface-cli download <model>) so the load hits warm cache.
4. Try a different network or disable VPN to rule out blackholed Xet/CDN endpoints.
5. Retry later if huggingface.co status shows CDN incidents.

Example fix

# before
orchestrator.load_model("unsloth/llama-3-8b")
# after (warm the cache first)
# huggingface-cli download unsloth/llama-3-8b
orchestrator.load_model("unsloth/llama-3-8b")

import urllib.request
urllib.request.urlopen("https://huggingface.co", timeout=5)  # fail fast before load

try:
    orchestrator.load_model(name)
except RuntimeError as e:
    if "Download stalled" in str(e):
        subprocess.run(["huggingface-cli", "download", name])  # out-of-band fallback
        orchestrator.load_model(name)

When it happens

Trigger: load_model for a model not in cache, where both the Xet-based and classic HTTP download paths stall past the stall-detection window — e.g. a proxy that blackholes large transfers, DNS/connectivity flakiness, or hub rate limiting.

Common situations: Corporate proxies or VPNs that time out hf-transfer/Xet chunks, unstable Wi-Fi, hub CDN issues, MTU/blackhole networking in containers, or extremely throttled links triggering the inactivity heuristic.

Related errors

• Metadata unavailable while resolving GGUF variant '{variant}
• '{repo}' is gated on Hugging Face and this model cannot be d
• Could not verify STT model '{model_id}'. Check that the repo
• STT model '{model_id}' is not downloaded. Download it in Set
• {unavailable_reason}

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/d4bce6c4a9a3e17f. Report an issue: GitHub.