unslothai/unsloth · error · RuntimeError

The pinned {spec.name} source archive is invalid

Error message

The pinned {spec.name} source archive is invalid

What it means

Outer exception translation around the whole extraction loop: tarfile.TarError, EOFError, or OSError during streaming/decompression/copy is re-raised as RuntimeError with this message. It normalizes structural archive failures (bad gzip, malformed tar headers, unexpected EOF from the bounded reader cascading as EOFError, filesystem OSErrors during staging writes) into the library's single error type.

Source

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

                            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:
    if runtime.is_symlink() or not runtime.is_dir():
        return False
    try:
        required_files = _configured_package_paths(
            spec.required_files,
            spec,

View on GitHub (pinned to 203007d190)

Solutions

  1. Inspect e.__cause__ — it preserves the original TarError/EOFError/OSError and pinpoints structure vs filesystem
  2. curl the URL and run `file` + `gzip -t` on the body; an HTML error page means the URL/mirror is wrong
  3. Check the cache volume: df -h and write permissions on cache_root()/third-party-sources
  4. Re-download/repack and re-pin if the canonical artifact is structurally bad

Example fix

// before
except RuntimeError:
    pass  # no diagnostics

// after
except RuntimeError as e:
    if "source archive is invalid" in str(e):
        logging.error("archive structure failure: %r", e.__cause__)
    raise
Defensive patterns

Strategy: try-catch

Validate before calling

import gzip
with open("source.tar.gz", "rb") as raw:
    head = raw.read(2)
assert head == b"\x1f\x8b", "body is not gzip — check archive_url"
gzip.open("source.tar.gz", "rb").read(1)  # full structural check needs full read; see tar validation

Try / catch

try:
    ensure_pinned_source(spec)
except RuntimeError as e:
    if "source archive is invalid" in str(e):
        log.error("structural archive failure, cause=%r", e.__cause__)
        raise

Prevention

When it happens

Trigger: Any of: gzip.GzipFile raising BadGzipFile/EOFError on corrupt compressed data; tarfile raising ReadError/StreamError in r| mode; OSError from destination_file.open/mkdir (permissions, disk full, quota) — all escape the inner loop into `except (tarfile.TarError, EOFError, OSError)`.

Common situations: Corrupt or non-gzip body served at archive_url (HTML error page saved as tar.gz); partial downloads; ENOSPC on the cache volume; read-only cache directory; the _BoundedArchiveReader's own 'expands too large' RuntimeError passes through untouched while structural errors map here.

Related errors

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