What causes "invalid hex in SHA-512 checksum: %w" in ipfs/kubo?

Print and inspect wantHex; ensure it is a pure hex string of exactly 128 characters (64 bytes) with no prefix or whitespace

ipfs/kubo · error

invalid hex in SHA-512 checksum: %w

Error message

invalid hex in SHA-512 checksum: %w

What it means

verifySHA512 validates that downloaded update-archive bytes match an expected hex-encoded SHA-512 digest. Before comparing, it hex-decodes the expected checksum string; if that string is not valid hexadecimal (odd length or non-hex characters), the decode fails and this error wraps the underlying hex error. It indicates a malformed checksum, not a content mismatch.

Source

Thrown at core/commands/update_github.go:261

	if err != nil {
		return fmt.Errorf("downloading checksum file: %w", err)
	}

	// 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

Print and inspect wantHex; ensure it is a pure hex string of exactly 128 characters (64 bytes) with no prefix or whitespace
Trim surrounding whitespace and strip any 'sha512:'/'sha512-' prefix before passing it in
Verify the source of the checksum (release metadata file) was parsed correctly and not truncated
Fall back to re-fetching the checksum from the trusted release source

Example fix

// before
verifySHA512(data, "sha512:" + checksumFromMeta)
// after
sum := strings.TrimPrefix(strings.TrimSpace(checksumFromMeta), "sha512:")
if err := verifySHA512(data, sum); err != nil { ... }

Defensive patterns

Strategy: validation

Validate before calling

sum := strings.TrimSpace(wantHex)
if n := len(sum); n != 128 || strings.TrimLeft(sum, "0123456789abcdefABCDEF") != "" {
    return fmt.Errorf("checksum must be 128 hex chars, got %d chars: %q", n, sum)
}
err := verifySHA512(data, sum)

Prevention

Store checksums as raw 128-char hex, no algorithm prefix
Trim whitespace before passing checksums to verify functions
Keep checksum source (release metadata) and asset from the same release snapshot

When it happens

Trigger: Calling downloadAndVerifySHA512 (or verifySHA512 directly, e.g. from an anonymous helper) with a wantHex string that has odd length or contains characters outside 0-9a-fA-F, such as a truncated checksum, a checksum with a 'sha512:' prefix, or one copied with stray whitespace/characters.

Common situations: A release-metadata file or config pinned the checksum incorrectly; a checksum was copy-pasted from a page that prefixed it with the algorithm name; the checksum string was sliced/truncated during parsing or templating.

Related errors

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