What causes "reading download: %w" in ipfs/kubo?

Simply retry the update command — transient network drops are the usual cause

reading download: %w

Error message

reading download: %w

What it means

downloadAsset reads the asset body through io.LimitReader capped at maxDownloadSize+1; this error wraps any failure during that streaming read (connection reset mid-body, timeout, TLS error, truncated transfer).

Source

Thrown at core/commands/update_github.go:230

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return nil, err
	}
	req.Header.Set("User-Agent", "kubo/"+version.CurrentVersionNumber)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, fmt.Errorf("downloading asset: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("download returned HTTP %d", resp.StatusCode)
	}

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

View on GitHub (pinned to 329838acdf)

Solutions

Simply retry the update command — transient network drops are the usual cause
Check network stability (MTU issues, VPN, flaky Wi-Fi) for repeated failures
Increase client timeout tolerance by running on a stable connection; the context deadline may be too tight
Verify the GitHub CDN (objects.githubusercontent.com) is reachable, not blocked by a firewall

Defensive patterns

Strategy: retry

Try / catch

err := runUpdate()
if err != nil {
	var netErr net.Error
	if errors.As(err, &netErr) || strings.Contains(err.Error(), "reading download") {
		// transient I/O failure mid-body: safe to retry the whole download
		return retryWithBackoff(runUpdate, 3)
	}
	return err
}

Prevention

Run updates on a stable wired connection; avoid VPN/mobile links for large downloads
Check MTU/firewall settings if downloads repeatedly stall or reset
Retry promptly — the error is almost always transient
Verify the context/timeout given to the updater is generous enough for archive-sized transfers

When it happens

Trigger: The TCP/TLS connection drops while the response body is being read, GitHub CDN closes the connection early, a context deadline cancels the in-flight read, or a proxy severs the transfer mid-stream.

Common situations: Flaky or slow networks during large kubo archive downloads; NAT/firewall dropping long-lived connections; corporate proxies with idle timeouts; pulling over VPN or mobile links.

Related errors

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