github/copilot-sdk · critical

checksum mismatch for

Error message

checksum mismatch for %s: expected %s, got %s

What it means

The bundler verifies release-tarball integrity by comparing the SHA-256 computed during download against an expected checksum (from the release manifest/checksums file). On mismatch it refuses to use the downloaded asset and reports asset name, expected, and actual hashes. This guards against corrupted or tampered downloads (supply-chain protection).

Solutions

1. Delete the cached/failed tarball and re-download; transient corruption is the most common cause.
2. Confirm the expected checksum corresponds to the same release version and platform asset being downloaded.
3. If the release was re-published, update the bundler (or checksum list) to the new checksums.
4. Do not bypass the check; investigate the source of corruption instead.

Example fix

// before: stale checksum pinned in release metadata
"expectedChecksum": "e3b0c44298fc1c14..."

// after: regenerate checksums for the republished release and update metadata
"expectedChecksum": "<sha256 of re-published tarball>"

// verify the pinned checksum matches the release version you target
want, ok := releaseChecksums[releaseVersion][assetName]
if !ok {
    return fmt.Errorf("no checksum pinned for %s@%s", assetName, releaseVersion)
}

if _, _, err := downloadCLIBinary(...); err != nil {
    if strings.Contains(err.Error(), "checksum mismatch") {
        purgeCache(); reDownloadWithFreshChecksums()
    }
    return err
}

When it happens

Trigger: fmt.Sprintf("%x", hasher.Sum(nil)) != expectedChecksum after a complete download — corrupted transfer, wrong checksum entry for the selected assetName, or a re-published release asset whose bytes changed.

Common situations: MITM or corrupted CDN cache serving different bytes; bundler version referencing a checksum from a different release; release maintainers re-uploading the asset; interrupted-but-truncated download that still closed cleanly.

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

• must be a SHA-256 hash ( bytes), got bytes
• %sRuntimeExecutableHash must be a SHA-256 hash
• %sRuntimeNodeHash must be a SHA-256 hash
• SHA256SUMS.txt does not contain
• runtime assets hash mismatch

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

Appendix: source

Thrown at go/cmd/bundler/main.go:1029

	// Save tarball to temp file
	tarballPath := filepath.Join(destDir, assetName)
	tarballFile, err := os.Create(tarballPath)
	if err != nil {
		return "", "", fmt.Errorf("failed to create tarball file: %w", err)
	}

	hasher := sha256.New()
	if _, err := io.Copy(io.MultiWriter(tarballFile, hasher), resp.Body); err != nil {
		tarballFile.Close()
		return "", "", fmt.Errorf("failed to save tarball: %w", err)
	}
	if err := tarballFile.Close(); err != nil {
		return "", "", fmt.Errorf("failed to close tarball file: %w", err)
	}
	actualChecksum := fmt.Sprintf("%x", hasher.Sum(nil))
	if actualChecksum != expectedChecksum {
		return "", "", fmt.Errorf(
			"checksum mismatch for %s: expected %s, got %s",
			assetName,
			expectedChecksum,
			actualChecksum,
		)
	}

	// The SDK release package intentionally omits the legacy SEA binary. Preserve
	// embeddedcli.Path compatibility by installing the runtime wrapper under the
	// historical copilot[.exe] name; the normal client path uses the adjacent
	// wrapper/runtime.node pair directly.
	binaryPath := filepath.Join(destDir, binaryName)
	wrapperName := runtimeWrapperName(binaryName)
	if err := extractFileFromTarball(
		tarballPath,
		destDir,
		"package/prebuilds/"+runtimePlatform+"/"+wrapperName,
		binaryName,

View on GitHub (pinned to cd8cf15dc3)