unslothai/unsloth · critical · RuntimeError

The cached {spec.name} source failed integrity validation

Error message

The cached {spec.name} source failed integrity validation

What it means

In _install_runtime, before copying files from the cached checkout into a fresh runtime staging dir, the checkout is re-validated with _sealed_source_manifest(checkout, spec); None means the on-disk cache no longer matches spec.source_tree_digest. The runtime build refuses to consume a cache that has drifted or been corrupted since installation.

Source

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

            if generated.read_bytes() != content:
                return False
        manifest = _runtime_manifest(runtime, spec)
        if spec.runtime_tree_digest is not None:
            return _manifest_digest(manifest) == spec.runtime_tree_digest
        return checkout is not None and manifest == _expected_runtime_manifest(checkout, spec)
    except (OSError, RuntimeError, ValueError):
        return False


def _install_runtime(runtime: Path, checkout: Path, spec: PinnedSource) -> None:
    workspace = Path(tempfile.mkdtemp(prefix = ".runtime-", dir = runtime.parent))
    staging = workspace / "runtime"
    staging.mkdir()
    try:
        if spec.source_tree_digest is not None:
            source_manifest = _sealed_source_manifest(checkout, spec)
            if source_manifest is None:
                raise RuntimeError(f"The cached {spec.name} source failed integrity validation")
        else:
            source_manifest = _checkout_manifest(checkout, spec)
        for relative, expected_digest in source_manifest.items():
            source_file = checkout / relative
            destination_file = staging / relative
            destination_file.parent.mkdir(parents = True, exist_ok = True)
            shutil.copy2(source_file, destination_file)
            if hashlib.sha256(destination_file.read_bytes()).hexdigest() != expected_digest:
                raise RuntimeError(f"{spec.name} source changed while preparing its runtime")
        for relative, content in _generated_file_contents(spec).items():
            destination_file = staging / relative
            destination_file.parent.mkdir(parents = True, exist_ok = True)
            destination_file.write_bytes(content)
        if not _valid_runtime(staging, spec, checkout):
            raise RuntimeError(f"The prepared {spec.name} runtime failed integrity validation")
        _replace_owned_directory(staging, runtime)
    finally:
        _remove_owned_path(workspace)

View on GitHub (pinned to 203007d190)

Solutions

1. Clear the cache for that spec: remove cache_root()/third-party-sources/<spec.name> and let ensure_pinned_source re-download and re-verify from scratch
2. Audit what mutated the tree (mtimes, auditd) if it recurs — a process writing into the cache is the root cause
3. Exclude the cache directory from sync/AV scanning
4. After a clean re-download the digest check should pass; if it does not, the pin digest itself is wrong (see 1595)

Example fix

# before: recurring failure from mutated cache
ensure_pinned_source(spec)  # raises: cached source failed integrity validation

# after: purge the spec's cache slice and rebuild
import shutil
shutil.rmtree(cache_root() / "third-party-sources" / spec.name, ignore_errors=True)
runtime = ensure_pinned_source(spec)

from studio.backend.utils.third_party_source import _sealed_source_manifest, cache_root
checkout = cache_root() / "third-party-sources" / spec.name / spec.revision / "source"
if spec.source_tree_digest is not None and _sealed_source_manifest(checkout, spec) is None:
    shutil.rmtree(cache_root() / "third-party-sources" / spec.name)  # purge and let it re-fetch

try:
    runtime = ensure_pinned_source(spec)
except RuntimeError as e:
    if "cached" in str(e) and "integrity" in str(e):
        shutil.rmtree(cache_root() / "third-party-sources" / spec.name, ignore_errors=True)
        runtime = ensure_pinned_source(spec)  # fallback: rebuild cache from canonical source

When it happens

Trigger: ensure_pinned_source reaches runtime preparation (runtime dir absent/invalid) and the previously installed checkout under cache_root()/third-party-sources/<name>/<revision>/source fails digest re-validation — files were modified, deleted, partially written, or replaced on disk.

Common situations: A build/tool/IDE wrote into the cached source tree; antivirus or sync tools (Dropbox/OneDrive) altered files; interrupted prior install left a half-populated cache; disk corruption; someone tampered with the cache deliberately.

Related errors

• The pinned {spec.name} source archive failed integrity valid
• The prepared {spec.name} runtime failed integrity validation
• Linked folder no longer resolves to its registered path
• Linked folder root identity changed
• Failed to delete dataset from {len(failures)} cache location

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