chenhg5/cc-connect · error

first-chunk: 206 without parseable Content-Range %q

Error message

first-chunk: 206 without parseable Content-Range %q

What it means

Thrown when the Feishu server responds 206 Partial Content but the Content-Range header cannot be parsed by parseContentRangeTotal — missing header, malformed, or 'bytes 0-0/*' with an unknown total. The chunked downloader needs the total size to plan and verify the chunk loop, so an unparseable header is a protocol violation it refuses to guess at. Like all first-chunk failures, this triggers the plain-GET fallback.

Source

Thrown at platform/feishu/resource_download.go:159

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, p.resourceURL(messageID, fileKey, resType), nil)
	if err != nil {
		return nil, 0, fmt.Errorf("build first-chunk request: %w", err)
	}
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Range", "bytes=0-0")

	resp, err := p.resourceDownloadHTTP.Do(req)
	if err != nil {
		return nil, 0, fmt.Errorf("first-chunk request: %w", err)
	}
	defer func() { _, _ = io.Copy(io.Discard, resp.Body); _ = resp.Body.Close() }()

	switch resp.StatusCode {
	case http.StatusPartialContent:
		cr := resp.Header.Get("Content-Range")
		total, ok := parseContentRangeTotal(cr)
		if !ok {
			return nil, 0, fmt.Errorf("first-chunk: 206 without parseable Content-Range %q", cr)
		}
		body, err := io.ReadAll(io.LimitReader(resp.Body, 1))
		if err != nil {
			return nil, 0, fmt.Errorf("read first-chunk body: %w", err)
		}
		return body, total, nil

	case http.StatusOK:
		// Server ignored Range and sent the full body. We deliberately
		// honour it and skip the chunked loop — this matches pre-#1741
		// behaviour for files small enough that Feishu doesn't truncate.
		body, err := io.ReadAll(io.LimitReader(resp.Body, p.resourceMaxBytes+1))
		if err != nil {
			return nil, 0, fmt.Errorf("read full body: %w", err)
		}
		if int64(len(body)) > p.resourceMaxBytes {
			return nil, 0, fmt.Errorf("resource too large: body exceeds cap %d", p.resourceMaxBytes)
		}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Rely on the automatic resourceSingleGet fallback — verify it succeeds in logs ('first-chunk fetch failed; trying plain GET')
2. Inspect the reported Content-Range value in the error to identify the intermediary mangling headers
3. Bypass or fix the proxy/CDN that strips or rewrites Content-Range

Example fix

null

null

null

if err != nil && strings.Contains(err.Error(), "parseable Content-Range") {
    // library already falls back to plain GET; surface a degraded-mode log
    slog.Warn("range unsupported by upstream; single-GET path used", "err", err)
}

When it happens

Trigger: resp.StatusCode == 206 while resp.Header.Get("Content-Range") is empty, lacks a '/' segment, ends with '/*', or has a non-numeric/invalid total (parseContentRangeTotal returns false).

Common situations: An intermediate proxy or non-Feishu-compatible server (e.g. in tests or custom-domain gateways) returning 206 without proper Content-Range; broken reverse-proxy caching layers mangling headers.

Related errors

• resource too large: total=%d exceeds cap %d
• build first-chunk request: %w
• first-chunk request: %w
• first-chunk: unexpected status %d
• Content-Range total mismatch: got %d want %d

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/3fcd2027d9b1ea02. Report an issue: GitHub.