proxy-range-header-forwarding

name	proxy-range-header-forwarding
description	Fix iOS AVPlayer "CoreMediaErrorDomain error -12939 - byte range length mismatch" or similar video streaming failures when a proxy/edge/CDN service sits between the client and object storage (GCS, S3, R2). Use when: (1) iOS video fails with -12939 "byte range length mismatch - should be length 2 is length N", (2) curl with Range: bytes=0-1 returns full file instead of 2 bytes, (3) one URL path works with Range but another path to the same storage doesn't, (4) proxy advertises Accept-Ranges: bytes but returns 200 with full file for range requests. The root cause is typically a proxy handler that constructs a new request to the backend without forwarding the client's Range header.
author	Claude Code
version	1.0.0
date	"2026-02-22T00:00:00.000Z"

Proxy Range Header Forwarding for Video Streaming

Problem

A proxy/edge service (Fastly Compute, Cloudflare Workers, custom reverse proxy) sits between clients and object storage. Some routes correctly forward HTTP Range headers to the storage backend, but other routes (added later or by different developers) construct backend requests from scratch without forwarding Range headers. This causes iOS AVPlayer to fail because it probes with Range: bytes=0-1 and rejects responses where the body size doesn't match the requested range.

Context / Trigger Conditions

• iOS error: CoreMediaErrorDomain error -12939 - byte range length mismatch - should be length 2 is length N
• PlatformException(VideoError, Failed to load video: Operation Stopped)
• curl -H "Range: bytes=0-1" on the failing URL returns 200 with Content-Length equal to full file size
• The same curl test on a different URL path to the same storage returns 206 with Content-Length: 2
• The proxy/edge code has multiple route handlers that independently construct backend requests
• Response headers include Accept-Ranges: bytes (misleadingly advertising support)

Root Cause Pattern

In proxy architectures, each route handler independently constructs requests to the storage backend. It's common for the "original" handler to properly forward Range headers while variant handlers (quality variants, thumbnails, transcoded versions) build requests from scratch without considering Range.

// BROKEN: Handler ignores client Range header
fn handle_variant(req: Request, path: &str) -> Response {
    let gcs_path = resolve_variant(path);
    let backend_req = Request::new(Method::GET, &gcs_url);  // No Range header!
    backend_req.send("storage")
}

// WORKING: Handler forwards Range header
fn handle_original(req: Request, path: &str) -> Response {
    let range = req.get_header("Range");  // Extracts Range
    let backend_req = Request::new(Method::GET, &gcs_url);
    if let Some(r) = range {
        backend_req.set_header("Range", r);  // Forwards it
    }
    backend_req.send("storage")
}

Solution

Three things must all be fixed in the proxy handler:

1. Extract Range header from client request

let range = req
    .get_header(header::RANGE)
    .and_then(|h| h.to_str().ok())
    .map(|s| s.to_string());

2. Forward Range header to storage backend

if let Some(range_value) = range {
    backend_req.set_header("Range", range_value);
}

3. Accept 206 responses from the backend

// BEFORE (broken): only accepts 200
match resp.get_status() {
    StatusCode::OK => Ok(resp),
    ...
}

// AFTER (fixed): accepts both 200 and 206
match resp.get_status() {
    StatusCode::OK | StatusCode::PARTIAL_CONTENT => Ok(resp),
    ...
}

GCS/S3/R2 natively handle Range headers and return proper 206 Partial Content with correct Content-Range and Content-Length headers, so once forwarded, the response can be passed through directly to the client.

Verification

# Test the failing endpoint with a range probe (what iOS does)
curl -sv -H "Range: bytes=0-1" "https://cdn.example.com/hash/variant" \
  -o /dev/null 2>&1 | grep -iE "< HTTP|content-length|content-range"

# Expected AFTER fix:
# < HTTP/2 206
# < content-range: bytes 0-1/TOTAL_SIZE
# < content-length: 2

# Test mid-file range
curl -sv -H "Range: bytes=1000-1999" "https://cdn.example.com/hash/variant" \
  -o /dev/null 2>&1 | grep -iE "< HTTP|content-length|content-range"

# Expected: 206, content-length: 1000, content-range: bytes 1000-1999/TOTAL

# Test full download still works (no Range header)
curl -sv "https://cdn.example.com/hash/variant" \
  -o /dev/null 2>&1 | grep -iE "< HTTP|content-length"

# Expected: 200, content-length: TOTAL_SIZE

Example

Real case: Fastly Compute edge service proxying to GCS. The /{hash} route (original blob) forwarded Range headers via download_blob(hash, range). The /{hash}/720p route (transcoded quality variant) called download_hls_from_gcs(gcs_key) with no range parameter.

Fix required changes in three layers:

1. Storage function: added range: Option<&str> parameter
2. Wrapper function: passed range through
3. Route handler: extracted Range from client request

Notes

• Audit all route handlers: If one handler is missing Range forwarding, others likely are too. Search for all places that construct backend requests and verify Range is forwarded.
• Don't just set Accept-Ranges: Adding Accept-Ranges: bytes to responses without actually handling ranges is worse than not advertising it - clients will expect it to work.
• iOS is strict: Safari/AVPlayer always probes with Range: bytes=0-1 before streaming. Chrome/Android are more forgiving and may work without proper Range support.
• HEAD requests: HEAD handlers don't need Range forwarding (they return metadata only), but GET handlers absolutely do.
• Cache layers: If a caching proxy sits in front, it may cache the full 200 response and serve it for Range requests. Purge cache after deploying the fix.

References

• MDN: HTTP Range Requests
• GCS: Resumable Downloads
• Apple: AVPlayer HTTP Live Streaming