unslothai/unsloth · error · RuntimeError

The pinned {spec.name} archive ended unexpectedly

Error message

The pinned {spec.name} archive ended unexpectedly

What it means

While copying a member's content, the reader returned an empty chunk before `remaining` (member.size) reached zero — the tar stream ended mid-file. This is the truncation detector: declared size and actual available bytes disagree, so the archive is incomplete or corrupt.

Source

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

                            _package_path_parts(relative, spec, kind = "archive")
                            if relative in extracted:
                                raise RuntimeError(
                                    f"The pinned {spec.name} archive contains duplicate files"
                                )
                            extracted.add(relative)
                            source_file = bundle.extractfile(member)
                            if source_file is None:
                                raise RuntimeError(
                                    f"The pinned {spec.name} archive contains an unreadable file"
                                )
                            destination_file = staging.joinpath(*parts[1:])
                            destination_file.parent.mkdir(parents = True, exist_ok = True)
                            remaining = member.size
                            with source_file, destination_file.open("wb") as handle:
                                while remaining:
                                    chunk = source_file.read(min(1024 * 1024, remaining))
                                    if not chunk:
                                        raise RuntimeError(
                                            f"The pinned {spec.name} archive ended unexpectedly"
                                        )
                                    handle.write(chunk)
                                    remaining -= len(chunk)
        except (tarfile.TarError, EOFError, OSError) as error:
            raise RuntimeError(f"The pinned {spec.name} source archive is invalid") from error
        if _sealed_source_manifest(staging, spec) is None:
            raise RuntimeError(f"The pinned {spec.name} source archive failed integrity validation")
        _replace_owned_directory(staging, destination)
    finally:
        _remove_owned_path(workspace)


def _valid_runtime(
    runtime: Path,
    spec: PinnedSource,
    checkout: Path | None = None,
) -> bool:

View on GitHub (pinned to 203007d190)

Solutions

  1. Re-run the install to force a fresh download into a new temp workspace
  2. Independently verify the artifact: curl the URL, gzip -t it, compare SHA-256 with the pin's expectation
  3. Check destination disk space (archive lands in destination.parent)
  4. If the canonical artifact itself is truncated at the host, pin a different mirror/revision
Defensive patterns

Strategy: retry

Validate before calling

import tarfile
with tarfile.open("source.tar.gz") as tf:
    for m in tf:
        if not m.isdir():
            f = tf.extractfile(m)
            got = 0
            while True:
                chunk = f.read(1024 * 1024)
                if not chunk:
                    break
                got += len(chunk)
            assert got == m.size, f"truncated member {m.name}: {got} != {m.size}"

Try / catch

for attempt in range(2):
    try:
        runtime = ensure_pinned_source(spec)
        break
    except RuntimeError as e:
        if "ended unexpectedly" not in str(e) or attempt == 1:
            raise

Prevention

When it happens

Trigger: source_file.read(min(1MiB, remaining)) returns b'' while remaining > 0 — the gzip/tar payload was cut short (truncated download that passed the outer size checks, or a tar whose header size exceeds its data).

Common situations: Interrupted or proxy-truncated downloads; gzip streams that decode partially before hitting garbage; archives whose entries lie about size; disk-full during download producing a short file.

Related errors

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