github/copilot-sdk · critical · RuntimeError

Checksum mismatch for

Error message

Checksum mismatch for {filename}:
  expected: {expected_hash}
  actual:   {actual}

What it means

_verify_checksum computes the SHA-256 hex digest of downloaded bytes and compares it to the published expected hash. On mismatch it raises this RuntimeError showing expected vs actual digests, guarding against corrupted or tampered downloads.

Solutions

Re-download the package (delete any cached copy first) and retry.
Verify the pinned version matches the checksums file version.
Switch networks/mirrors to rule out a corrupted transfer path.
Set COPILOT_CLI_PATH to a manually installed, independently verified binary.
If tampering is suspected, re-fetch checksums from the official release source.

Example fix

# before
assert hashlib.sha256(data).hexdigest() == expected_hash  # fails
# after
import hashlib
if hashlib.sha256(data).hexdigest() != expected_hash:
    data = refetch_package(version)  # retry download, then re-verify

Defensive patterns

Strategy: retry

Validate before calling

import hashlib
if hashlib.sha256(data).hexdigest() != expected_hash:
    raise RuntimeError("checksum mismatch — re-download required")

Try / catch

for attempt in range(3):
    try:
        data = download_package(version, platform)
        _verify_checksum(data, expected_hash, filename)
        break
    except RuntimeError:
        if attempt == 2: raise

Prevention

Delete cached downloads before retrying
Verify pinned versions match published checksums
Use official mirrors only
Independently verify binaries when setting COPILOT_CLI_PATH
Investigate repeated mismatches as possible tampering

When it happens

Trigger: _fetch_verified_release_package downloads a release package whose sha256 does not match the checksums file — interrupted/corrupted download, truncated body, or a mismatched version/package pair.

Common situations: Unstable network truncating large downloads; mirror serving stale artifacts; CDN caching an old package; MITM or tampering.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — 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/e2453d1078f0d9b2. Report an issue: GitHub.

Appendix: source

Thrown at python/copilot/_cli_download.py:159

            "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()
    if actual != expected_hash:
        raise RuntimeError(
            f"Checksum mismatch for {filename}:\n  expected: {expected_hash}\n  actual:   {actual}"
        )


def _fetch_verified_release_package(version: str, runtime_platform: str) -> bytes:
    """Download and verify the unified platform release package."""
    asset_name = get_release_asset_name(version, runtime_platform)
    expected_hash = _fetch_checksums(version).get(asset_name)
    if not expected_hash:
        raise RuntimeError(f"SHA256SUMS.txt does not contain {asset_name}.")
    url = get_download_url(version, asset_name)
    data = _fetch_url_bytes(url, timeout=600)
    _verify_checksum(data, expected_hash, asset_name)
    return data


def _runtime_bundle_is_complete(pair_dir: Path, wrapper_name: str) -> bool:
    required = (

View on GitHub (pinned to cd8cf15dc3)