{"record":{"id":"b2d30b7d218e42a7","repo":"unslothai/unsloth","slug":"the-pinned-spec-name-source-archive-is-invalid","errorCode":null,"errorMessage":"The pinned {spec.name} source archive is invalid","messagePattern":"The pinned (.+?) source archive is invalid","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/utils/third_party_source.py","lineNumber":692,"sourceCode":"                            source_file = bundle.extractfile(member)\n                            if source_file is None:\n                                raise RuntimeError(\n                                    f\"The pinned {spec.name} archive contains an unreadable file\"\n                                )\n                            destination_file = staging.joinpath(*parts[1:])\n                            destination_file.parent.mkdir(parents = True, exist_ok = True)\n                            remaining = member.size\n                            with source_file, destination_file.open(\"wb\") as handle:\n                                while remaining:\n                                    chunk = source_file.read(min(1024 * 1024, remaining))\n                                    if not chunk:\n                                        raise RuntimeError(\n                                            f\"The pinned {spec.name} archive ended unexpectedly\"\n                                        )\n                                    handle.write(chunk)\n                                    remaining -= len(chunk)\n        except (tarfile.TarError, EOFError, OSError) as error:\n            raise RuntimeError(f\"The pinned {spec.name} source archive is invalid\") from error\n        if _sealed_source_manifest(staging, spec) is None:\n            raise RuntimeError(f\"The pinned {spec.name} source archive failed integrity validation\")\n        _replace_owned_directory(staging, destination)\n    finally:\n        _remove_owned_path(workspace)\n\n\ndef _valid_runtime(\n    runtime: Path,\n    spec: PinnedSource,\n    checkout: Path | None = None,\n) -> bool:\n    if runtime.is_symlink() or not runtime.is_dir():\n        return False\n    try:\n        required_files = _configured_package_paths(\n            spec.required_files,\n            spec,","sourceCodeStart":674,"sourceCodeEnd":710,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/third_party_source.py#L674-L710","documentation":"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.","triggerScenarios":"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)`.","commonSituations":"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.","solutions":["Inspect e.__cause__ — it preserves the original TarError/EOFError/OSError and pinpoints structure vs filesystem","curl the URL and run `file` + `gzip -t` on the body; an HTML error page means the URL/mirror is wrong","Check the cache volume: df -h and write permissions on cache_root()/third-party-sources","Re-download/repack and re-pin if the canonical artifact is structurally bad"],"exampleFix":"// before\nexcept RuntimeError:\n    pass  # no diagnostics\n\n// after\nexcept RuntimeError as e:\n    if \"source archive is invalid\" in str(e):\n        logging.error(\"archive structure failure: %r\", e.__cause__)\n    raise","handlingStrategy":"try-catch","validationCode":"import gzip\nwith open(\"source.tar.gz\", \"rb\") as raw:\n    head = raw.read(2)\nassert head == b\"\\x1f\\x8b\", \"body is not gzip — check archive_url\"\ngzip.open(\"source.tar.gz\", \"rb\").read(1)  # full structural check needs full read; see tar validation","typeGuard":null,"tryCatchPattern":"try:\n    ensure_pinned_source(spec)\nexcept RuntimeError as e:\n    if \"source archive is invalid\" in str(e):\n        log.error(\"structural archive failure, cause=%r\", e.__cause__)\n        raise","preventionTips":["Smoke-test archive_url with curl | file in CI to catch HTML error pages saved as tar.gz","Keep the cache volume writable and non-full; many OSErrors during staging surface as this message"],"tags":["tarfile","gzip","corrupt-archive","error-wrapping","extraction"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}