github/copilot-sdk · error · RuntimeError

Copilot runtime wrapper and runtime.node must both be…

Error message

Copilot runtime wrapper and runtime.node must both be non-empty.

What it means

Raised by ensure_runtime_wrapper after staging the Copilot runtime: the wrapper script and the native runtime.node binary must both exist as files and have a non-zero size before the staging directory is finalized and made executable. The library throws this to prevent promoting a corrupted or incomplete runtime download into the cache.

Solutions

Delete the Copilot CLI/runtime cache directory so the runtime is re-downloaded from scratch.
Re-run the download (download_cli / main) on a stable network connection and confirm disk space is available.
Check antivirus/quota software for interference with large binary files in the cache path.
If it persists, verify the release assets themselves are intact (asset names/checksums) for your platform.

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
wrapper, runtime = Path(staged_wrapper), Path(staged_runtime)
if not (wrapper.is_file() and runtime.is_file() and wrapper.stat().st_size > 0 and runtime.stat().st_size > 0):
    raise RuntimeError("staged runtime assets incomplete; re-download")

Try / catch

try:
    ensure_runtime_wrapper(...)
except RuntimeError as e:
    if "non-empty" in str(e):
        clear_cache_and_redownload()

Prevention

Ensure stable network and adequate disk space before downloading the runtime.
Exclude cache directories from antivirus scanning.
Verify staged files exist and are non-empty before promoting them.

When it happens

Trigger: Calling download_cli(), ensure_runtime_library(), main(), or the runtime entrypoint resolvers when a staged download produced an empty or missing wrapper/runtime.node file (e.g. truncated download, interrupted copy, or disk full).

Common situations: Network outage mid-download leaving zero-byte files; antivirus or disk-quota stripping the staged runtime.node; a corrupted package cache being re-staged.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at python/copilot/_cli_download.py:363

            "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
        ):
            raise RuntimeError("Copilot runtime wrapper and runtime.node must both be non-empty.")
        if sys.platform != "win32":
            staged_wrapper.chmod(
                staged_wrapper.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
            )
        (staging_dir / assets_marker.name).write_text("1\n", encoding="ascii")
        try:
            if pair_dir.exists() and (force or not assets_marker.is_file()):
                shutil.rmtree(pair_dir, ignore_errors=True)
            staging_dir.replace(pair_dir)
        except OSError:
            if (
                wrapper_path.is_file()
                and wrapper_path.stat().st_size > 0
                and runtime_path.is_file()
                and runtime_path.stat().st_size > 0
                and assets_marker.is_file()
            ):
                return str(wrapper_path)

View on GitHub (pinned to cd8cf15dc3)