github/copilot-sdk · error · RuntimeError

Failed to download checksums from

Error message

Failed to download checksums from {url}: {exc}

If you are in an offline or firewalled environment, set COPILOT_CLI_PATH to point to a manually-installed binary.

What it means

_fetch_checksums downloads the SHA256SUMS file for a release and converts it to text. If the HTTP fetch fails (RuntimeError from _fetch_url_bytes, e.g. network error or non-200) or the body is not valid UTF-8, it raises this RuntimeError with remediation advice pointing to COPILOT_CLI_PATH for offline use.

Solutions

  1. Restore network access or configure proxy environment variables (HTTPS_PROXY).
  2. Set COPILOT_CLI_PATH to a manually installed copilot binary to skip download entirely.
  3. Verify the requested version exists and has a checksums file published.
  4. Retry in case of transient network failure.

Example fix

# before
python -c "from copilot._cli_download import _fetch_verified_release_package; _fetch_verified_release_package('v1.2.3', 'linux')"
# after
export COPILOT_CLI_PATH=/usr/local/bin/copilot  # skip download entirely
Defensive patterns

Strategy: fallback

Validate before calling

import socket
try:
    socket.create_connection(("github.com", 443), timeout=5)
except OSError:
    raise SystemExit("network unavailable — set COPILOT_CLI_PATH instead")

Try / catch

try:
    package = _fetch_verified_release_package(version, platform)
except RuntimeError as exc:
    if "Failed to download checksums" in str(exc):
        binary = os.environ.get("COPILOT_CLI_PATH") or fail(exc)

Prevention

When it happens

Trigger: Calling _fetch_verified_release_package (e.g. during CLI auto-download) while offline, behind a firewall/proxy that blocks the checksums URL, when the version has no published checksums file (404), or when the server returns a binary/encoded body.

Common situations: Air-gapped CI runners; corporate proxies; pinned version that was yanked; DNS failures in containers.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at python/copilot/_cli_download.py:139

    return None


def _should_skip_download() -> bool:
    """Check if auto-download is disabled via environment variable."""
    val = os.environ.get("COPILOT_SKIP_CLI_DOWNLOAD", "").lower()
    return val in ("1", "true", "yes")


def _fetch_checksums(version: str) -> dict[str, str]:
    """Fetch and parse the SHA256SUMS.txt file.

    Returns a dict mapping filename → sha256 hex digest.
    """
    url = get_checksums_url(version)
    try:
        text = _fetch_url_bytes(url, timeout=30).decode("utf-8")
    except (RuntimeError, UnicodeDecodeError) as exc:
        raise RuntimeError(
            f"Failed to download checksums from {url}: {exc}\n\n"
            "If you are in an offline or firewalled environment, set "
            "COPILOT_CLI_PATH to point to a manually-installed binary."
        ) from exc

    checksums: dict[str, str] = {}
    for line in text.strip().splitlines():
        parts = line.split()
        if len(parts) == 2 and re.fullmatch(r"[a-fA-F0-9]{64}", parts[0]):
            digest, filename = parts
            # Some formats use *filename (binary mode indicator)
            checksums[filename.lstrip("*")] = digest.lower()
    return checksums


def _verify_checksum(data: bytes, expected_hash: str, filename: str) -> None:
    """Verify SHA-256 checksum of downloaded data."""
    actual = hashlib.sha256(data).hexdigest()

View on GitHub (pinned to cd8cf15dc3)