github/copilot-sdk · error · RuntimeError

SHA256SUMS.txt does not contain

Error message

SHA256SUMS.txt does not contain {asset_name}.

What it means

_fetch_verified_release_package downloads a pinned Copilot release asset and verifies it against SHA256SUMS.txt before use. This error is raised when the fetched checksum manifest does not list the asset name computed for the requested version/platform, so verification cannot proceed.

Solutions

  1. Verify the pinned version actually publishes the expected asset name (check get_release_asset_name output against the release's SHA256SUMS.txt).
  2. Upgrade the SDK to a version whose asset naming matches the release's manifest.
  3. Set COPILOT_CLI_PATH to an existing binary to bypass download entirely.
  4. Clear any cached checksum files and retry in case a stale manifest was cached.

Example fix

// before
CLI_VERSION = "0.1.0"  # release predates unified package naming
// after
CLI_VERSION = "0.2.1"  # release whose SHA256SUMS.txt lists the computed asset name
Defensive patterns

Strategy: validation

Validate before calling

from copilot._cli_download import get_release_asset_name, _fetch_checksums
asset = get_release_asset_name(CLI_VERSION, get_runtime_platform())
if asset not in _fetch_checksums(CLI_VERSION):
    raise SystemExit(f"release {CLI_VERSION} lacks asset {asset}; pin another version")

Try / catch

try:
    wrapper = ensure_runtime_wrapper()
except RuntimeError as e:
    if "does not contain" in str(e):
        wrapper = fallback_to_local_cli()  # COPILOT_CLI_PATH
    else:
        raise

Prevention

When it happens

Trigger: Calling ensure_runtime_wrapper/download_cli (or _fetch_verified_release_package directly) where get_release_asset_name(version, runtime_platform) produces an asset name absent from SHA256SUMS.txt — typically a version/platform mismatch or a manifest format change.

Common situations: Pinning a CLI_VERSION that was published before the unified platform package existed; a renamed or restructured release asset on GitHub; a partially published release where SHA256SUMS.txt was uploaded before the asset (or vice versa); a proxy serving a stale/cached checksum file.

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/1fe1c22cc05f7ace. Report an issue: GitHub.

Appendix: source

Thrown at python/copilot/_cli_download.py:169

            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 = (
        pair_dir / wrapper_name,
        pair_dir / "runtime.node",
        pair_dir / _HOSTLESS_ASSETS_MARKER,
    )
    return all(path.is_file() and path.stat().st_size > 0 for path in required)


def download_cli(version: str | None = None, *, force: bool = False) -> str:
    """Provision a complete runtime bundle with a ``copilot[.exe]`` alias.

View on GitHub (pinned to cd8cf15dc3)