github/copilot-sdk · error · RuntimeError

Incomplete Copilot runtime bundle in

Error message

Incomplete Copilot runtime bundle in {pair_dir}: {wrapper_name} and runtime.node are required.

What it means

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'.

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.

Example fix

# before
ensure_runtime_wrapper()  # half-written cache
# after
import shutil
shutil.rmtree(get_cache_dir(CLI_VERSION), ignore_errors=True)
ensure_runtime_wrapper(force=True)

Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
pair = get_cache_dir(CLI_VERSION) / "prebuilds" / get_runtime_platform()
files = [pair / n for n in ("copilot-runtime", "runtime.node")]
states = [f.is_file() and f.stat().st_size > 0 for f in files]
if any(states) and not all(states):
    shutil.rmtree(pair)  # clean partial bundle before provisioning

Try / catch

try:
    wrapper = ensure_runtime_wrapper()
except RuntimeError as e:
    if "Incomplete Copilot runtime bundle" in str(e):
        clear_runtime_cache(); wrapper = ensure_runtime_wrapper(force=True)
    else:
        raise

Prevention

Avoid killing provisioning processes mid-extraction.
Exclude runtime caches from aggressive disk cleaners.
Serialize provisioning; don't run concurrent processes on one cache.

When it happens

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

Common situations: Killed download/extraction processes leaving half-written caches; aggressive disk cleaners; concurrent processes racing on the same cache directory.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at python/copilot/_cli_download.py:338

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(
            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"

View on GitHub (pinned to cd8cf15dc3)