unslothai/unsloth · error · RuntimeError

The pinned {spec.name} archive contains an unreadable file

Error message

The pinned {spec.name} archive contains an unreadable file

What it means

After validation, the installer calls bundle.extractfile(member); for a non-regular member (or a member that cannot be exposed as a stream in r| mode) tarfile returns None instead of raising. This guard converts that silent None into an explicit error so the copy loop never dereferences a missing stream.

Source

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

                                    f"The pinned {spec.name} archive contains a non-regular file"
                                )
                            uncompressed_bytes += member.size
                            if uncompressed_bytes > _ARCHIVE_MAX_UNCOMPRESSED_BYTES:
                                raise RuntimeError(
                                    f"The pinned {spec.name} archive expands too large"
                                )
                            if len(parts) < 3 or parts[1] != spec.package:
                                continue
                            relative = "/".join(parts[1:])
                            _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")

View on GitHub (pinned to 203007d190)

Solutions

  1. Validate the archive locally: gzip -t source.tar.gz && tar -tzf source.tar.gz > /dev/null to detect corruption
  2. Re-download the archive (the temp workspace is discarded on failure) — truncated transfers sometimes produce this shape
  3. Repack from the canonical revision export and re-pin
  4. Verify SHA-256 of the downloaded file against the expected artifact digest
Defensive patterns

Strategy: retry

Validate before calling

import tarfile
with tarfile.open("source.tar.gz") as tf:
    for m in tf:
        if m.isfile() and tf.extractfile(m) is None:
            raise SystemExit(f"member unreadable in stream: {m.name}")

Try / catch

try:
    ensure_pinned_source(spec)
except RuntimeError as e:
    if "unreadable file" in str(e):
        runtime = ensure_pinned_source(spec)  # fresh download into a new temp workspace

Prevention

When it happens

Trigger: bundle.extractfile(member) returns None for a member that passed earlier checks — in practice rare, occurring with unusual member types, stream-mode (r|) limitations, or corrupt headers where extractfile cannot produce a file object.

Common situations: Corrupt/truncated archive where headers claim a regular file but no data stream follows; unusual tar formats (sparse/pcrl special records) that tarfile lists but cannot extract in stream mode; usually accompanies a broader integrity failure (see 1593/1595).

Related errors

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