unslothai/unsloth · critical · RuntimeError

The pinned {spec.name} source archive failed integrity valid

Error message

The pinned {spec.name} source archive failed integrity validation

What it means

After extraction completes, _sealed_source_manifest(staging, spec) recomputes the extracted tree's digest manifest and compares it against spec.source_tree_digest; returning None means mismatch. This is the trust anchor of the whole pipeline: even if every structural check passed, the bytes on disk must hash exactly to the pinned value, so a tampered archive can never be installed.

Source

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

                                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,
            kind = "required",
        )

View on GitHub (pinned to 203007d190)

Solutions

  1. Recompute the tree digest from the freshly downloaded canonical archive and update source_tree_digest in the pin (and runtime_tree_digest together, per the paired-digest rule)
  2. Ensure the digest was derived using the same normalization the library applies in _sealed_source_manifest (path set + file content hashes) — reuse the library's helper rather than a naive tarball hash
  3. Pin immutable URLs (codeload for an exact SHA) so content can never drift
  4. If the digest was correct and still fails, suspect local tampering or disk corruption — audit the host

Example fix

# before: digest from ad-hoc script
source_tree_digest = sha256_of_tarball_bytes  # wrong basis

# after: digest from the library's own manifest over the extracted tree
from studio.backend.utils import third_party_source as tps
source_tree_digest = tps.tree_digest_of(staging_dir)  # same normalization as validation
Defensive patterns

Strategy: validation

Validate before calling

# validate before installing: extract to a temp dir and re-run the library's own manifest
import tempfile
from studio.backend.utils.third_party_source import _sealed_source_manifest
with tempfile.TemporaryDirectory() as td:
    extract(spec.archive_url, td)  # your trusted extraction
    assert _sealed_source_manifest(Path(td), spec) is not None, "digest mismatch — fix pin"

Try / catch

try:
    ensure_pinned_source(spec)
except RuntimeError as e:
    if "failed integrity validation" in str(e):
        # do NOT bypass; recompute digest from the canonical artifact and update the pin

Prevention

When it happens

Trigger: The extracted staging tree's computed manifest differs from the pinned source_tree_digest — archive content was modified relative to the pin (revised files at the same URL, repacked archive, or a genuinely wrong digest in the spec).

Common situations: Upstream force-pushed the tagged revision or the host regenerates tarballs (mtime/normalization differences change the tree digest); pinning a digest computed from a different export format than archive_url serves; typo'd digest; supply-chain substitution at the mirror.

Related errors

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