{"record":{"id":"50c2e227ba72f7f2","repo":"github/copilot-sdk","slug":"copilot-runtime-bundle-is-not-cached-in-pair-dir","errorCode":null,"errorMessage":"Copilot runtime bundle is not cached in {pair_dir} and automatic downloads are disabled.","messagePattern":"Copilot runtime bundle is not cached in (.+?) and automatic downloads are disabled\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/copilot/_cli_download.py","lineNumber":343,"sourceCode":"        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\"\n        if (\n            not staged_wrapper.is_file()\n            or staged_wrapper.stat().st_size == 0\n            or not staged_runtime.is_file()\n            or staged_runtime.stat().st_size == 0","sourceCodeStart":325,"sourceCodeEnd":361,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/_cli_download.py#L325-L361","documentation":"When the runtime bundle is absent from the cache and a download would be required, the library checks _should_skip_download() (typically COPILOT_CLI_SKIP_DOWNLOAD / offline mode). If downloads are disabled it raises this error instead of fetching the release package.","triggerScenarios":"ensure_runtime_wrapper (or its callers) finds no cached copilot-runtime/runtime.node for the pinned version while the skip-download environment flag is set — e.g. COPILOT_CLI_SKIP_DOWNLOAD=1 or an equivalent offline setting.","commonSituations":"CI/offline environments configured to forbid downloads but missing a pre-populated cache; Docker images built with skip-download enabled then run without bundling the runtime; air-gapped installs.","solutions":["Pre-provision the runtime cache (run once with downloads enabled, then copy the cache into the offline environment).","Unset the skip-download environment variable to allow automatic downloads.","Point COPILOT_CLI_PATH at an existing runtime binary.","Bake the runtime bundle into your Docker image at build time."],"exampleFix":"# before\nENV COPILOT_CLI_SKIP_DOWNLOAD=1  # but no cache baked in\n# after\nRUN python -c \"from copilot._cli_download import ensure_runtime_wrapper; ensure_runtime_wrapper()\"\nENV COPILOT_CLI_SKIP_DOWNLOAD=1","handlingStrategy":"fallback","validationCode":"import os\nfrom copilot._cli_download import get_cache_dir, get_runtime_platform\npair = get_cache_dir(CLI_VERSION) / \"prebuilds\" / get_runtime_platform()\nskip = bool(os.environ.get(\"COPILOT_CLI_SKIP_DOWNLOAD\"))\nif skip and not (pair / \"runtime.node\").is_file():\n    raise SystemExit(\"skip-download set but runtime not cached; pre-provision the cache\")","typeGuard":null,"tryCatchPattern":"try:\n    wrapper = ensure_runtime_wrapper()\nexcept RuntimeError as e:\n    if \"automatic downloads are disabled\" in str(e):\n        wrapper = provision_from_bundled_cache()  # pre-packaged artifacts\n    else:\n        raise","preventionTips":["In offline/skip-download environments, always pre-provision and ship the runtime cache.","Bake runtime bundles into container images at build time.","Document the skip-download flag's requirement for a warm cache."],"tags":["configuration","offline","cache","environment-variable"],"backgroundTag":"missing-env-var","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"}