{"record":{"id":"e85d2d9f5cd4c97d","repo":"unslothai/unsloth","slug":"the-prepared-spec-name-runtime-failed-integrity","errorCode":null,"errorMessage":"The prepared {spec.name} runtime failed integrity validation","messagePattern":"The prepared (.+?) runtime failed integrity validation","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/utils/third_party_source.py","lineNumber":766,"sourceCode":"        if spec.source_tree_digest is not None:\n            source_manifest = _sealed_source_manifest(checkout, spec)\n            if source_manifest is None:\n                raise RuntimeError(f\"The cached {spec.name} source failed integrity validation\")\n        else:\n            source_manifest = _checkout_manifest(checkout, spec)\n        for relative, expected_digest in source_manifest.items():\n            source_file = checkout / relative\n            destination_file = staging / relative\n            destination_file.parent.mkdir(parents = True, exist_ok = True)\n            shutil.copy2(source_file, destination_file)\n            if hashlib.sha256(destination_file.read_bytes()).hexdigest() != expected_digest:\n                raise RuntimeError(f\"{spec.name} source changed while preparing its runtime\")\n        for relative, content in _generated_file_contents(spec).items():\n            destination_file = staging / relative\n            destination_file.parent.mkdir(parents = True, exist_ok = True)\n            destination_file.write_bytes(content)\n        if not _valid_runtime(staging, spec, checkout):\n            raise RuntimeError(f\"The prepared {spec.name} runtime failed integrity validation\")\n        _replace_owned_directory(staging, runtime)\n    finally:\n        _remove_owned_path(workspace)\n\n\ndef ensure_pinned_source(\n    spec: PinnedSource, *, legacy_sources: tuple[Path | str, ...] = ()\n) -> Path:\n    revision = spec.revision.lower()\n    if _REVISION_PATTERN.fullmatch(revision) is None or revision != spec.revision:\n        raise RuntimeError(f\"{spec.name} source revision must be a lowercase full Git commit\")\n    for digest in (spec.source_tree_digest, spec.runtime_tree_digest):\n        if digest is not None and _SHA256_PATTERN.fullmatch(digest) is None:\n            raise RuntimeError(f\"{spec.name} source digest must be a lowercase SHA-256\")\n    if (spec.source_tree_digest is None) != (spec.runtime_tree_digest is None):\n        raise RuntimeError(f\"{spec.name} source and runtime digests must be configured together\")\n\n    parent = cache_root() / \"third-party-sources\" / spec.name","sourceCodeStart":748,"sourceCodeEnd":784,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/third_party_source.py#L748-L784","documentation":"Final self-check in _install_runtime: after copying sources and writing generated files into staging, _valid_runtime(staging, spec, checkout) re-validates the assembled tree (including runtime_tree_digest); failure aborts before _replace_owned_directory promotes it. It guarantees an installed runtime is never promoted unless it byte-for-byte matches the pinned runtime digest.","triggerScenarios":"The assembled staging runtime fails _valid_runtime — generated file contents (_generated_file_contents) don't match what the runtime digest was pinned against, the manifest copy is incomplete, or runtime_tree_digest in the spec is stale relative to the code that generates runtime files.","commonSituations":"Library upgrade changed generated runtime files but the pin's runtime_tree_digest was not recomputed; mismatched pair where source_tree_digest is current but runtime_tree_digest is from an older revision; filesystem issues dropping a file during staging.","solutions":["Recompute runtime_tree_digest from a known-good assembled runtime and update the pin (keeping the paired source/runtime digests in sync)","Check free space and permissions on the cache volume — a silently skipped write fails validation","Purge the spec's cache slice and retry to eliminate a corrupted intermediate","If it persists on a clean cache, the pin's digests and the library's _generated_file_contents are inconsistent — regenerate both digests with the same library version"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"# regenerate digests with the same library version that will validate them\nfrom studio.backend.utils import third_party_source as tps\nassert spec.runtime_tree_digest == tps.compute_runtime_digest(assembled_runtime_dir), (\n    \"runtime digest stale — re-pin before deploying\"\n)","typeGuard":null,"tryCatchPattern":"try:\n    ensure_pinned_source(spec)\nexcept RuntimeError as e:\n    if \"prepared\" in str(e) and \"runtime\" in str(e):\n        # purge cache and retry once; persistent failure means stale runtime_tree_digest in the pin","preventionTips":["Regenerate both source_tree_digest and runtime_tree_digest together whenever the library version changes","Add a CI step that bootstraps every pin on a clean cache so digest staleness fails the build, not production"],"tags":["integrity","digest","runtime","pinned-source","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}