ipfs/kubo · error

download exceeds maximum size of %d bytes

Error message

download exceeds maximum size of %d bytes

What it means

downloadAsset enforces a hard cap (maxDownloadSize) on every downloaded artifact to prevent unbounded memory use; it reads maxDownloadSize+1 bytes and fails if more than maxDownloadSize arrived, meaning the payload is implausibly large for a release asset.

Source

Thrown at core/commands/update_github.go:233

	}
	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))
	if len(fields) < 1 {
		return fmt.Errorf("empty or malformed .sha512 file")
	}

View on GitHub (pinned to 329838acdf)

Solutions

1. Verify the network is not serving a captive portal or proxy interstitial page (open a browser and complete any login)
2. Check DNS resolution for github.com/objects.githubusercontent.com (ISP hijacking)
3. Inspect what the URL actually returns: `curl -sI <asset-url>` to see content type and length
4. Retry from a clean, unrestricted network connection

// detect proxy/captive-portal interference before trusting 200 responses
resp, err := http.Get(assetURL)
if err == nil {
	ct := resp.Header.Get("Content-Type")
	if !strings.Contains(ct, "application/") && !strings.Contains(ct, "gzip") && ct != "" {
		return fmt.Errorf("unexpected content type %q — proxy or captive portal interference", ct)
	}
	resp.Body.Close()
}

if err := runUpdate(); err != nil {
	if strings.Contains(err.Error(), "exceeds maximum size") {
		// almost certainly a proxy/portal returning non-asset content; check network
		log.Print("download is implausibly large: check for captive portal or proxy")
	}
	return err
}

When it happens

Trigger: The download endpoint returns a body larger than maxDownloadSize: a captive portal or proxy serving a huge HTML error page with a 200 status, a misconfigured mirror, or an unexpectedly bloated/unexpected artifact at the URL.

Common situations: Corporate proxies or hotel/captive Wi-Fi that return 200 with an HTML interstitial instead of the binary; DNS hijacking by an ISP; pointing the updater at a non-GitHub mirror serving different content.

Related errors

• download returned HTTP %d
• reading download: %w
• downloading checksum file: %w
• nothing downloaded by ipfs fetcher
• no local swarm address for migration node

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