unslothai/unsloth · error · RuntimeError

Could not download the pinned {spec.name} source archive

Error message

Could not download the pinned {spec.name} source archive

What it means

Catch-all translation at the end of _download_archive: any OSError or urllib.error.URLError raised during the HTTP request/transfer is re-raised as RuntimeError with this message (chained via `from error`). The library normalizes all transport-level failures — DNS failure, connection refused, TLS errors, HTTP error responses surfaced as URLError subclasses — into one deterministic exception type.

Source

Thrown at studio/backend/utils/third_party_source.py:596

                    if time.monotonic() >= deadline:
                        raise RuntimeError(
                            f"Timed out downloading the pinned {spec.name} source archive"
                        )
                    chunk = read_chunk(1024 * 1024)
                    if time.monotonic() >= deadline:
                        raise RuntimeError(
                            f"Timed out downloading the pinned {spec.name} source archive"
                        )
                    if not chunk:
                        break
                    total += len(chunk)
                    if total > _ARCHIVE_MAX_DOWNLOAD_BYTES:
                        raise RuntimeError(f"The pinned {spec.name} archive is too large")
                    handle.write(chunk)
    except RuntimeError:
        raise
    except (OSError, urllib.error.URLError) as error:
        raise RuntimeError(f"Could not download the pinned {spec.name} source archive") from error


def _archive_member_parts(member: tarfile.TarInfo, spec: PinnedSource) -> tuple[str, ...]:
    name = member.name[:-1] if member.isdir() and member.name.endswith("/") else member.name
    parts = tuple(name.split("/"))
    if (
        not name
        or name.startswith("/")
        or "\\" in name
        or any(part in ("", ".", "..") for part in parts)
        or any(PureWindowsPath(part).drive for part in parts)
        or parts[0] != _archive_root_name(spec)
    ):
        raise RuntimeError(f"Invalid path in the pinned {spec.name} source archive")
    return parts


class _BoundedArchiveReader:

View on GitHub (pinned to 203007d190)

Solutions

1. Inspect the chained cause: `except RuntimeError as e: print(e.__cause__)` reveals the underlying URLError/OSError and its reason
2. Verify the URL responds: curl -IL <archive_url>; fix the pin if it 404s
3. Fix environment egress: proxy env vars (HTTPS_PROXY), CA bundle (REQUESTS_CA_BUNDLE / SSL_CERT_FILE) for TLS-intercepting proxies, DNS
4. Retry after transient 5xx/network blips — the download is idempotent into a fresh temp workspace

Example fix

// before
try:
    runtime = ensure_pinned_source(spec)
except RuntimeError as e:
    print(e)  # opaque message

// after
try:
    runtime = ensure_pinned_source(spec)
except RuntimeError as e:
    if "Could not download" in str(e) and e.__cause__:
        logging.error("download failed: %r", e.__cause__)
    raise

import urllib.request
with urllib.request.urlopen(spec.archive_url, timeout=30) as r:
    assert r.status == 200, f"archive host returned {r.status}"

try:
    runtime = ensure_pinned_source(spec)
except RuntimeError as e:
    cause = e.__cause__
    if "Could not download" in str(e) and isinstance(cause, urllib.error.URLError):
        log.error("transport failure: %r", cause.reason)

When it happens

Trigger: urllib.request.urlopen raised: DNS resolution failure for the archive host, connection refused/reset mid-transfer, TLS certificate verification failure, or an HTTPError (404/403/5xx) for archive_url. Any of these escapes the loop and hits `except (OSError, urllib.error.URLError)`.

Common situations: Offline or firewalled CI without egress to the archive host; expired/rotated URL (GitHub archive URLs can disappear); corporate TLS-intercepting proxy with an untrusted CA; typo in archive_url; rate-limited (403) by the CDN.

Related errors

• The pinned {spec.name} archive is too large
• Download stalled for '{model_name}' even with HF_HUB_DISABLE
• Metadata unavailable while resolving GGUF variant '{variant}
• VirusTotal upload failed after {attempts} attempt(s): {last_
• '{repo}' is gated on Hugging Face and this model cannot be d

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