github/copilot-sdk · error · RuntimeError

Unsupported runtime package entry

Error message

Unsupported runtime package entry: {member.name}

What it means

_materialize_runtime_bundle iterates every tar member and only processes regular files and directories. Any other entry type (symlinks, hardlinks, devices, fifos) is rejected with this error to prevent link-based attacks and unsupported package layouts.

Solutions

1. Download only official, checksum-verified release packages.
2. Re-download and re-verify the archive in case of corruption.
3. Inspect the tarball (tar -tvf) to see which member is not a regular file.
4. File an issue with the publisher if an official release contains link members.

import tarfile
with tarfile.open("pkg.tgz") as t:
    special = [m.name for m in t.getmembers() if not (m.isfile() or m.isdir())]
    if special:
        raise SystemExit(f"unsupported members: {special}")

try:
    ensure_runtime_wrapper()
except RuntimeError as e:
    if "Unsupported runtime package entry" in str(e):
        reverify_and_redownload_package()
    else:
        raise

When it happens

Trigger: A runtime release tarball containing symlink/hardlink or special-file members is passed to ensure_runtime_wrapper/_materialize_runtime_bundle.

Common situations: A release package rebuilt with symlinks (e.g. vendored shared libs linked instead of copied); tampered archives; unofficial repackaged artifacts.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Unsafe runtime package path
• Unsafe runtime asset inventory path:
• Runtime asset escapes cache directory:
• Checksum mismatch for
• Failed to read runtime package entry

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

Appendix: source

Thrown at python/copilot/_cli_download.py:310

    if top_level == "prebuilds":
        if len(relative) < 3 or relative[1] != runtime_platform:
            return None
        relative = relative[2:]
    destination = Path(*relative)
    if destination.is_absolute() or ".." in destination.parts:
        raise RuntimeError(f"Unsafe runtime package path: {member_name}")
    return destination


def _materialize_runtime_bundle(data: bytes, runtime_platform: str, destination: Path) -> None:
    """Extract the hostless runtime tree, retaining unknown package assets by default."""
    with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as archive:
        for member in archive:
            relative = _hostless_runtime_path(member.name, runtime_platform)
            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

View on GitHub (pinned to cd8cf15dc3)