github/copilot-sdk · error · RuntimeError

No runtime version is pinned.

Error message

No runtime version is pinned.

What it means

ensure_runtime_wrapper provisions the Copilot runtime pair from a release package and needs a pinned version. Like download_cli, it refuses to run with an unpinned CLI_VERSION (development install) and raises this error.

Solutions

  1. Install a published wheel that embeds CLI_VERSION.
  2. Set COPILOT_CLI_PATH to an existing runtime/CLI binary.
  3. Pass version=<release> explicitly to ensure_runtime_wrapper.
  4. Rebuild the package so the version stamping step runs.

Example fix

# before
ensure_runtime_wrapper()  # dev install, CLI_VERSION empty
# after
ensure_runtime_wrapper(version="0.2.1")
# or set COPILOT_CLI_PATH
Defensive patterns

Strategy: validation

Validate before calling

import copilot._cli_download as d
if not (d.CLI_VERSION or os.environ.get("COPILOT_CLI_PATH")):
    raise SystemExit("pin a runtime version or set COPILOT_CLI_PATH")

Try / catch

try:
    wrapper = ensure_runtime_wrapper()
except RuntimeError as e:
    if "No runtime version is pinned" in str(e):
        wrapper = os.environ["COPILOT_CLI_PATH"]
    else:
        raise

Prevention

When it happens

Trigger: Calling ensure_runtime_wrapper(), or any caller that reaches it (download_cli, ensure_runtime_library, main, _resolve_runtime_entrypoint, _resolve_inprocess_runtime), with no version argument while CLI_VERSION is empty.

Common situations: Running from a source/editable install where CLI_VERSION was never stamped; forgetting to set COPILOT_CLI_PATH in dev environments.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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

Appendix: source

Thrown at python/copilot/_cli_download.py:325

            if relative is None or member.isdir():
                continue
            if not member.isfile():
                raise RuntimeError(f"Unsupported runtime package entry: {member.name}")
            extracted = archive.extractfile(member)
            if extracted is None:
                raise RuntimeError(f"Failed to read runtime package entry: {member.name}")
            target = destination / relative
            target.parent.mkdir(parents=True, exist_ok=True)
            target.write_bytes(extracted.read())
            if sys.platform != "win32":
                target.chmod(member.mode & 0o777)


def ensure_runtime_wrapper(version: str | None = None, force: bool = False) -> str:
    """Provision the runtime pair and retained assets from the release package."""
    ver = version or CLI_VERSION
    if not ver:
        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(

View on GitHub (pinned to cd8cf15dc3)