github/copilot-sdk · error · RuntimeError

Copilot runtime bundle is not cached in

Error message

Copilot runtime bundle is not cached in {pair_dir} and automatic downloads are disabled.

What it means

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.

Solutions

1. Pre-provision the runtime cache (run once with downloads enabled, then copy the cache into the offline environment).
2. Unset the skip-download environment variable to allow automatic downloads.
3. Point COPILOT_CLI_PATH at an existing runtime binary.
4. Bake the runtime bundle into your Docker image at build time.

Example fix

# before
ENV COPILOT_CLI_SKIP_DOWNLOAD=1  # but no cache baked in
# after
RUN python -c "from copilot._cli_download import ensure_runtime_wrapper; ensure_runtime_wrapper()"
ENV COPILOT_CLI_SKIP_DOWNLOAD=1

import os
from copilot._cli_download import get_cache_dir, get_runtime_platform
pair = get_cache_dir(CLI_VERSION) / "prebuilds" / get_runtime_platform()
skip = bool(os.environ.get("COPILOT_CLI_SKIP_DOWNLOAD"))
if skip and not (pair / "runtime.node").is_file():
    raise SystemExit("skip-download set but runtime not cached; pre-provision the cache")

try:
    wrapper = ensure_runtime_wrapper()
except RuntimeError as e:
    if "automatic downloads are disabled" in str(e):
        wrapper = provision_from_bundled_cache()  # pre-packaged artifacts
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Invalid value ' '. Expected 'inprocess', 'stdio', or unset.
• Invalid value ' '. Expected 'inprocess', 'stdio', or unset.
• gitHubToken and useLoggedInUser cannot be used with…
• sessionFs.initialCwd is required
• sessionFs.sessionStatePath is required

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/50c2e227ba72f7f2. Report an issue: GitHub.

Appendix: source

Thrown at python/copilot/_cli_download.py:343

        raise RuntimeError("No runtime version is pinned.")
    runtime_platform = get_runtime_platform()
    wrapper_name = "copilot-runtime.exe" if sys.platform == "win32" else "copilot-runtime"
    pair_dir = get_cache_dir(ver) / "prebuilds" / runtime_platform
    wrapper_path = pair_dir / wrapper_name
    runtime_path = pair_dir / "runtime.node"
    assets_marker = pair_dir / _HOSTLESS_ASSETS_MARKER

    wrapper_exists = wrapper_path.is_file() and wrapper_path.stat().st_size > 0
    runtime_exists = runtime_path.is_file() and runtime_path.stat().st_size > 0
    if _runtime_bundle_is_complete(pair_dir, wrapper_name) and not force:
        return str(wrapper_path)
    if not force and wrapper_exists != runtime_exists:
        raise RuntimeError(
            f"Incomplete Copilot runtime bundle in {pair_dir}: "
            f"{wrapper_name} and runtime.node are required."
        )
    if _should_skip_download():
        raise RuntimeError(
            f"Copilot runtime bundle is not cached in {pair_dir} "
            "and automatic downloads are disabled."
        )

    data = _fetch_verified_release_package(ver, runtime_platform)
    import shutil

    pair_dir.parent.mkdir(parents=True, exist_ok=True)
    staging_dir = Path(tempfile.mkdtemp(dir=pair_dir.parent, prefix=".runtime-bundle-"))
    try:
        _materialize_runtime_bundle(data, runtime_platform, staging_dir)
        staged_wrapper = staging_dir / wrapper_name
        staged_runtime = staging_dir / "runtime.node"
        if (
            not staged_wrapper.is_file()
            or staged_wrapper.stat().st_size == 0
            or not staged_runtime.is_file()
            or staged_runtime.stat().st_size == 0

View on GitHub (pinned to cd8cf15dc3)