ipfs/kubo · error

SHA-512 mismatch: expected %s, got %x

Error message

SHA-512 mismatch: expected %s, got %x

What it means

verifySHA512 computes SHA-512 over the downloaded data and compares it to the expected hex digest. When the digests differ, it reports the expected checksum and the hex of the actual digest. This means the downloaded archive's content does not match the published checksum — the download is treated as corrupt or tampered and the update aborts.

Source

Thrown at core/commands/update_github.go:265

	// Parse "<hex>  <filename>\n" format (standard sha512sum output).
	fields := strings.Fields(string(checksumData))
	if len(fields) < 1 {
		return fmt.Errorf("empty or malformed .sha512 file")
	}
	wantHex := fields[0]

	return verifySHA512(data, wantHex)
}

// verifySHA512 checks that data matches the given hex-encoded SHA-512 hash.
func verifySHA512(data []byte, wantHex string) error {
	want, err := hex.DecodeString(wantHex)
	if err != nil {
		return fmt.Errorf("invalid hex in SHA-512 checksum: %w", err)
	}
	got := sha512.Sum512(data)
	if !bytes.Equal(got[:], want) {
		return fmt.Errorf("SHA-512 mismatch: expected %s, got %x", wantHex, got[:])
	}
	return nil
}

// assetNameForPlatformTag returns the expected archive filename for a given
// release tag and the current GOOS/GOARCH.
func assetNameForPlatformTag(tag string) string {
	ext := "tar.gz"
	if runtime.GOOS == "windows" {
		ext = "zip"
	}
	return fmt.Sprintf("kubo_%s_%s-%s.%s", tag, runtime.GOOS, runtime.GOARCH, ext)
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Re-download the archive (clear any cache/proxy) and retry the update
2. Compare the reported 'got' digest with the digest published on the release page / dist server to see which side is wrong
3. Check for proxy/CDN interference (fetch via a different network or direct URL)
4. If the release itself was re-published, refresh the local checksum source before retrying

// No caller-side validation can prevent it; optionally pre-hash locally:
want, _ := hex.DecodeString(wantHex)
got := sha512.Sum512(data)
fmt.Printf("local digest %x vs expected %x\n", got[:], want)

if err := downloadAndVerifySHA512(url, wantHex); err != nil {
    var mErr interface{ Mismatch() bool }
    if strings.Contains(err.Error(), "SHA-512 mismatch") {
        // re-download once, then surface the digests to the user
        return retryDownload(url, wantHex, 1)
    }
    return err
}

When it happens

Trigger: downloadAndVerifySHA512 fetched an archive whose bytes hash to a digest different from wantHex: partial/interrupted download, a CDN/proxy serving different or cached content, or the checksum corresponds to a different release artifact.

Common situations: Flaky network truncating a large archive mid-download; corporate proxy or mirror serving stale files; the checksum in the release index was updated (release replaced) but the old binary/URL was fetched; wrong checksum recorded for a platform-specific asset.

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

• downloading checksum file: %w
• nothing downloaded by ipfs fetcher
• download returned HTTP %d
• reading download: %w
• download exceeds maximum size of %d bytes

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/6581d33c7984b03c. Report an issue: GitHub.