What causes "chunk download size incorrect, expected=%d, got=%d" in AlistGo/alist?

Let the built-in retry (errNeedRetry) run first — transient short reads usually recover.

chunk download size incorrect, expected=%d, got=%d

Error message

chunk download size incorrect, expected=%d, got=%d

What it means

After copying a chunk body, the downloader verifies the byte count matches the chunk's expected size; a mismatch is wrapped in errNeedRetry so the chunk (or the request) is retried. Causes include premature connection closes, servers ignoring Range and sending truncated data, or proxies cutting the transfer.

Source

Thrown at internal/net/request.go:462

		}
		return 0, errOverloadRetry
	}
	defer resp.Body.Close()
	//only check file size on the first task
	if ch.id == 0 {
		err = d.checkTotalBytes(resp)
		if err != nil {
			return 0, err
		}
	}
	d.sendChunkTask(true)
	n, err := utils.CopyWithBuffer(ch.buf, resp.Body)

	if err != nil {
		return n, &errNeedRetry{err: err}
	}
	if n != ch.size {
		err = fmt.Errorf("chunk download size incorrect, expected=%d, got=%d", ch.size, n)
		return n, &errNeedRetry{err: err}
	}

	return n, nil
}
func (d *downloader) getParamsFromChunk(ch *chunk) *HttpRequestParams {
	var params HttpRequestParams
	awsutil.Copy(&params, d.params)

	// Get the getBuf byte range of data
	params.Range = http_range.Range{Start: ch.start, Length: ch.size}
	return &params
}

func (d *downloader) checkTotalBytes(resp *http.Response) error {
	var err error
	totalBytes := int64(-1)
	contentRange := resp.Header.Get("Content-Range")

View on GitHub (pinned to 843d9dc814)

Solutions

Let the built-in retry (errNeedRetry) run first — transient short reads usually recover.
Refresh the cached file metadata (size) if the upstream file may have changed; the size mismatch with totalBytes is the sibling symptom.
If the server has broken Range support, avoid chunked download for that storage or fix the server.
Stabilize the network path (disable aggressive proxying, check MTU/VPN).

Defensive patterns

Strategy: retry

Type guard

var retryable *errNeedRetry
if errors.As(err, &retryable) { /* chunk can be re-fetched */ }

Try / catch

if e, ok := err.(*errNeedRetry); ok && strings.Contains(e.Error(), "chunk download size incorrect") {
    // re-probe size, then re-download the chunk with fresh range
}

Prevention

Re-fetch file metadata when short-read errors cluster on one file (upstream size changed).
Verify servers you integrate actually honor Range before enabling chunked download.
Let errNeedRetry retries exhaust before escalating — most short reads are transient.

When it happens

Trigger: io.CopyN-style copy of resp.Body returns fewer bytes than ch.size (short read); server closes the connection mid-chunk; server mishandles the Range header so the body length differs from the requested range length.

Common situations: Flaky networks or mobile connections; remote servers with broken Range support; content changed size between the initial HEAD/probe and the ranged GET (file replaced upstream); interception by proxies that truncate bodies.

Related errors

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/6f6a416d9563c205. Report an issue: GitHub.