github/copilot-sdk · error

runtime assets hash mismatch

Error message

runtime assets hash mismatch

What it means

installRuntimeAssets computes sha256 over the read archive bytes and compares with config.RuntimeAssetsHash. A mismatch aborts extraction. The library verifies integrity so corrupted or mismatched runtime assets are never written to disk.

Solutions

1. Recompute the SHA-256 of the archive and update config.RuntimeAssetsHash
2. Re-download or re-embed the runtime archive and retry
3. Ensure asset and hash are produced together by the same build step
4. Check intermediary caches/proxies for stale artifacts

Example fix

// before
RuntimeAssetsHash: []byte(oldHash) // mismatch after assets rebuilt
// after
archive, _ := os.ReadFile("runtime.tar.gz")
sum := sha256.Sum256(archive)
cfg.RuntimeAssets = bytes.NewReader(archive)
cfg.RuntimeAssetsHash = sum[:]

archive, err := io.ReadAll(src)
if err != nil { return err }
sum := sha256.Sum256(archive)
if !bytes.Equal(sum[:], cfg.RuntimeAssetsHash) {
    return fmt.Errorf("archive hash %x != expected %x; rebuild assets", sum, cfg.RuntimeAssetsHash)
}

err := embeddedcli.InstallRuntime(ctx, cfg, dir)
if err != nil && strings.Contains(err.Error(), "runtime assets hash mismatch") {
    return fmt.Errorf("stale or corrupted runtime archive: re-download/re-embed and regenerate its hash")
}

When it happens

Trigger: sha256(RuntimeAssets bytes) != config.RuntimeAssetsHash: the embedded archive was rebuilt without updating the hash, the download was corrupted, or a different archive version was supplied with a stale hash.

Common situations: Regenerating runtime assets in CI but forgetting to regenerate RuntimeAssetsHash; proxy/cache serving a stale archive; truncation during a partial download.

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

• checksum mismatch for
• opening runtime assets
• existing hash mismatch
• Checksum mismatch for
• SHA256SUMS.txt does not contain

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

Appendix: source

Thrown at go/internal/embeddedcli/embeddedcli.go:376

	if reader != nil && len(hash) != sha256.Size {
		panic(fmt.Sprintf("%s must be a SHA-256 hash (%d bytes), got %d bytes", name, sha256.Size, len(hash)))
	}
}

func installRuntimeAssets(installDir string) error {
	if config.RuntimeAssets == nil || runtimeAssetsInstalled {
		return nil
	}
	archiveBytes, err := io.ReadAll(config.RuntimeAssets)
	if closer, ok := config.RuntimeAssets.(io.Closer); ok {
		closer.Close()
	}
	if err != nil {
		return fmt.Errorf("reading runtime assets: %w", err)
	}
	actual := sha256.Sum256(archiveBytes)
	if !bytes.Equal(actual[:], config.RuntimeAssetsHash) {
		return fmt.Errorf("runtime assets hash mismatch")
	}
	gzipReader, err := gzip.NewReader(bytes.NewReader(archiveBytes))
	if err != nil {
		return fmt.Errorf("opening runtime assets: %w", err)
	}
	defer gzipReader.Close()
	tarReader := tar.NewReader(gzipReader)
	for {
		header, err := tarReader.Next()
		if err == io.EOF {
			break
		}
		if err != nil {
			return fmt.Errorf("reading runtime assets: %w", err)
		}
		if header.Typeflag != tar.TypeReg {
			continue
		}

View on GitHub (pinned to cd8cf15dc3)