unslothai/unsloth · error · RuntimeError

The pinned {spec.name} archive is too large

Error message

The pinned {spec.name} archive is too large

What it means

Raised while downloading a pinned third-party source archive when the server's Content-Length header advertises a negative size or one exceeding _ARCHIVE_MAX_DOWNLOAD_BYTES. This is a pre-flight guard: the library refuses to start (or continue) a download that would exceed the configured byte budget. It exists to protect the host from oversized or malicious archives before any bytes are written to disk.

Source

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

    request = urllib.request.Request(url, headers = {"User-Agent": "Unsloth-Studio"})
    deadline = time.monotonic() + _ARCHIVE_DOWNLOAD_DEADLINE_SECONDS
    try:
        if time.monotonic() >= deadline:
            raise RuntimeError(f"Timed out downloading the pinned {spec.name} source archive")
        with urllib.request.urlopen(
            request,
            timeout = _ARCHIVE_SOCKET_TIMEOUT_SECONDS,
        ) as response:
            if time.monotonic() >= deadline:
                raise RuntimeError(f"Timed out downloading the pinned {spec.name} source archive")
            content_length = response.headers.get("Content-Length")
            if content_length is not None:
                try:
                    advertised_size = int(content_length)
                except ValueError as error:
                    raise RuntimeError(f"Invalid {spec.name} archive response size") from error
                if advertised_size < 0 or advertised_size > _ARCHIVE_MAX_DOWNLOAD_BYTES:
                    raise RuntimeError(f"The pinned {spec.name} archive is too large")
            total = 0
            read_chunk = getattr(response, "read1", None)
            if not callable(read_chunk):
                read_chunk = response.read
            with destination.open("wb") as handle:
                while True:
                    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)

View on GitHub (pinned to 203007d190)

Solutions

  1. Verify spec.archive_url points at the intended slim source tarball (e.g. the codeload GitHub tar.gz for the pinned revision), not a full bundle or release asset with binaries
  2. Check the advertised size with curl -I <archive_url> and compare against the library's _ARCHIVE_MAX_DOWNLOAD_BYTES constant
  3. If the larger archive is legitimately required, raise _ARCHIVE_MAX_DOWNLOAD_BYTES in your fork/config after confirming the digest still matches spec.source_tree_digest
  4. If the size looks malicious or the URL was repointed, update the pin (revision + source_tree_digest) to a trusted URL

Example fix

// before
PinnedSource(
    name="foo",
    package="foo",
    revision="1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    archive_url="https://example.com/foo-full-repo-bundle.tar.gz",  # oversized artifact
    source_tree_digest="...",
)

// after
PinnedSource(
    name="foo",
    package="foo",
    revision="1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    archive_url="https://codeload.github.com/org/foo/tar.gz/1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    source_tree_digest="...",
)
Defensive patterns

Strategy: validation

Validate before calling

import urllib.request
from studio.backend.utils.third_party_source import _ARCHIVE_MAX_DOWNLOAD_BYTES

req = urllib.request.Request(spec.archive_url, method="HEAD")
with urllib.request.urlopen(req, timeout=30) as r:
    length = int(r.headers.get("Content-Length", 0))
assert 0 <= length <= _ARCHIVE_MAX_DOWNLOAD_BYTES, f"archive too large: {length}"

Type guard

def archive_size_ok(spec) -> bool:
    if spec.archive_url is None:
        return False
    with urllib.request.urlopen(urllib.request.Request(spec.archive_url, method="HEAD"), timeout=30) as r:
        cl = r.headers.get("Content-Length")
    return cl is None or (cl.isdigit() and int(cl) <= _ARCHIVE_MAX_DOWNLOAD_BYTES)

Try / catch

try:
    ensure_pinned_source(spec)
except RuntimeError as e:
    if "archive is too large" in str(e):
        # fix the pin (wrong artifact) rather than retry

Prevention

When it happens

Trigger: A HEAD/GET response for spec.archive_url returns Content-Length > _ARCHIVE_MAX_DOWNLOAD_BYTES (or a parseable negative value). Happens when the pinned URL points to a bloated tarball, a wrong artifact, or a compromised/hostile mirror that lies about size.

Common situations: Bumping a dependency to a version whose source tarball is larger than the built-in cap; accidentally pinning archive_url to a full repository bundle or binary SDK instead of the slim source tarball; a proxy injecting a bogus Content-Length.

Related errors

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