{"record":{"id":"8370e5e44a466dac","repo":"github/copilot-sdk","slug":"incomplete-copilot-runtime-bundle-in-pair-dir","errorCode":null,"errorMessage":"Incomplete Copilot runtime bundle in {pair_dir}: {wrapper_name} and runtime.node are required.","messagePattern":"Incomplete Copilot runtime bundle in (.+?): (.+?) and runtime\\.node are required\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/copilot/_cli_download.py","lineNumber":338,"sourceCode":"\ndef ensure_runtime_wrapper(version: str | None = None, force: bool = False) -> str:\n    \"\"\"Provision the runtime pair and retained assets from the release package.\"\"\"\n    ver = version or CLI_VERSION\n    if not ver:\n        raise RuntimeError(\"No runtime version is pinned.\")\n    runtime_platform = get_runtime_platform()\n    wrapper_name = \"copilot-runtime.exe\" if sys.platform == \"win32\" else \"copilot-runtime\"\n    pair_dir = get_cache_dir(ver) / \"prebuilds\" / runtime_platform\n    wrapper_path = pair_dir / wrapper_name\n    runtime_path = pair_dir / \"runtime.node\"\n    assets_marker = pair_dir / _HOSTLESS_ASSETS_MARKER\n\n    wrapper_exists = wrapper_path.is_file() and wrapper_path.stat().st_size > 0\n    runtime_exists = runtime_path.is_file() and runtime_path.stat().st_size > 0\n    if _runtime_bundle_is_complete(pair_dir, wrapper_name) and not force:\n        return str(wrapper_path)\n    if not force and wrapper_exists != runtime_exists:\n        raise RuntimeError(\n            f\"Incomplete Copilot runtime bundle in {pair_dir}: \"\n            f\"{wrapper_name} and runtime.node are required.\"\n        )\n    if _should_skip_download():\n        raise RuntimeError(\n            f\"Copilot runtime bundle is not cached in {pair_dir} \"\n            \"and automatic downloads are disabled.\"\n        )\n\n    data = _fetch_verified_release_package(ver, runtime_platform)\n    import shutil\n\n    pair_dir.parent.mkdir(parents=True, exist_ok=True)\n    staging_dir = Path(tempfile.mkdtemp(dir=pair_dir.parent, prefix=\".runtime-bundle-\"))\n    try:\n        _materialize_runtime_bundle(data, runtime_platform, staging_dir)\n        staged_wrapper = staging_dir / wrapper_name\n        staged_runtime = staging_dir / \"runtime.node\"","sourceCodeStart":320,"sourceCodeEnd":356,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/_cli_download.py#L320-L356","documentation":"The runtime bundle consists of two required files: copilot-runtime[.exe] and runtime.node. This error is raised when exactly one of the two exists (non-empty) in the cache's prebuilds/<platform> directory — a partially extracted or partially deleted bundle that the library will not silently 'fix'.","triggerScenarios":"ensure_runtime_wrapper finds wrapper_exists != runtime_exists and force is not set — e.g. a previous extraction was interrupted, one file was deleted, or disk cleanup removed one of the pair.","commonSituations":"Killed download/extraction processes leaving half-written caches; aggressive disk cleaners; concurrent processes racing on the same cache directory.","solutions":["Delete the version's cache directory (get_cache_dir(ver)) and re-run so the bundle is re-provisioned from scratch.","Re-run with force=True to force a clean re-download.","Avoid running multiple provisioning processes concurrently on the same cache.","Check disk space to rule out a failed write during extraction."],"exampleFix":"# before\nensure_runtime_wrapper()  # half-written cache\n# after\nimport shutil\nshutil.rmtree(get_cache_dir(CLI_VERSION), ignore_errors=True)\nensure_runtime_wrapper(force=True)","handlingStrategy":"try-catch","validationCode":"from pathlib import Path\npair = get_cache_dir(CLI_VERSION) / \"prebuilds\" / get_runtime_platform()\nfiles = [pair / n for n in (\"copilot-runtime\", \"runtime.node\")]\nstates = [f.is_file() and f.stat().st_size > 0 for f in files]\nif any(states) and not all(states):\n    shutil.rmtree(pair)  # clean partial bundle before provisioning","typeGuard":null,"tryCatchPattern":"try:\n    wrapper = ensure_runtime_wrapper()\nexcept RuntimeError as e:\n    if \"Incomplete Copilot runtime bundle\" in str(e):\n        clear_runtime_cache(); wrapper = ensure_runtime_wrapper(force=True)\n    else:\n        raise","preventionTips":["Avoid killing provisioning processes mid-extraction.","Exclude runtime caches from aggressive disk cleaners.","Serialize provisioning; don't run concurrent processes on one cache."],"tags":["cache","corruption","runtime-bundle"],"backgroundTag":"invalid-state-transition","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}