What causes "downloading checksum file: %w" in ipfs/kubo?

Wait and retry — the .sha512 sidecar may not be uploaded/propagated yet

downloading checksum file: %w

Error message

downloading checksum file: %w

What it means

downloadAndVerifySHA512 fetches the `<archiveURL>.sha512` sidecar file via downloadAsset before verifying the archive; this error wraps any failure of that download (non-200 status, network error, oversized body), so the archive cannot be checksum-verified.

Source

Thrown at core/commands/update_github.go:244

	}

	data, err := io.ReadAll(io.LimitReader(resp.Body, maxDownloadSize+1))
	if err != nil {
		return nil, fmt.Errorf("reading download: %w", err)
	}
	if int64(len(data)) > maxDownloadSize {
		return nil, fmt.Errorf("download exceeds maximum size of %d bytes", maxDownloadSize)
	}
	return data, nil
}

// downloadAndVerifySHA512 downloads the .sha512 sidecar file for the given
// archive URL and verifies the archive data against it.
func downloadAndVerifySHA512(ctx context.Context, data []byte, archiveURL string) error {
	sha512URL := archiveURL + ".sha512"
	checksumData, err := downloadAsset(ctx, sha512URL)
	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)
	}

View on GitHub (pinned to 329838acdf)

Solutions

Wait and retry — the .sha512 sidecar may not be uploaded/propagated yet
Confirm the .sha512 file exists on the release page next to the archive
Check the inner error message: 'download returned HTTP 404' means the sidecar is missing; 429/5xx means retry later
If persistent, report the missing sidecar on the kubo release issue tracker

Defensive patterns

Strategy: retry

Validate before calling

// verify the sidecar URL responds 200 before starting the whole update
resp, err := http.Head(archiveURL + ".sha512")
if err != nil || resp.StatusCode != http.StatusOK {
	return fmt.Errorf(".sha512 sidecar not available yet; retry later")
}

Try / catch

err := runUpdate()
if err != nil {
	if strings.Contains(err.Error(), "downloading checksum file") {
		// sidecar download failed; likely still uploading after a fresh release
		return retryWithBackoff(runUpdate, 3)
	}
	return err
}

Prevention

Wait until the release page shows both the archive and its .sha512 file before updating
Back off on 429/5xx — the updater makes consecutive requests and can hit rate limits
Keep an unthrottled network path to github.com during updates
Fall back to manual download + `sha512sum -c` if the sidecar stays unavailable

When it happens

Trigger: The .sha512 sidecar is missing from the release (404), the checksum file is not yet uploaded while the archive is, GitHub rate-limits the second request, or the network drops during the checksum download.

Common situations: Updating immediately after a release where the archive was uploaded but the checksum sidecar is still propagating; deleted/partial releases; rate limiting because the updater makes several requests in quick succession.

Related errors

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