valyala/fasthttp · warning

byte range %q is invalid for empty content

Error message

byte range %q is invalid for empty content

What it means

The suffix form 'bytes=-N' means 'last N bytes'. This is meaningless when the resource is empty (Content-Length <= 0), so ParseByteRange rejects it instead of returning a bogus range.

Source

Thrown at fs.go:1504

	b = b[len(strBytes):]
	if len(b) == 0 || b[0] != '=' {
		return 0, 0, fmt.Errorf("missing byte range in %q", byteRange)
	}
	b = b[1:]

	n := bytes.IndexByte(b, '-')
	if n < 0 {
		return 0, 0, fmt.Errorf("missing the end position of byte range in %q", byteRange)
	}

	if n == 0 {
		v, err := ParseUint(b[n+1:])
		if err != nil {
			return 0, 0, err
		}
		if contentLength <= 0 {
			return 0, 0, fmt.Errorf("byte range %q is invalid for empty content", byteRange)
		}
		startPos := max(contentLength-v, 0)
		return startPos, contentLength - 1, nil
	}

	if startPos, err = ParseUint(b[:n]); err != nil {
		return 0, 0, err
	}
	if startPos >= contentLength {
		return 0, 0, fmt.Errorf("the start position of byte range cannot exceed %d. byte range %q", contentLength-1, byteRange)
	}

	b = b[n+1:]
	if len(b) == 0 {
		return startPos, contentLength - 1, nil
	}

	if endPos, err = ParseUint(b); err != nil {

View on GitHub (pinned to c96f600972)

Solutions

1. Ensure the file actually has content before range-serving it — check size on the client with a HEAD request first
2. Handle the error server-side by falling back to serving the full (empty) body with 200
3. If the file was truncated by a rotation/refresh, retry after the writer finishes
4. For direct calls, guard: only pass contentLength > 0 when using suffix ranges

Example fix

// caller guard
if contentLength > 0 {
    start, end, err = fs.ParseByteRange(rangeHdr, contentLength)
} else {
    start, end, err = 0, -1, nil // serve empty body
}

if contentLength <= 0 && isSuffixRange(hdr) {
    // skip range negotiation; serve empty body with 200
}

func suffixRangeValid(hdr []byte, contentLength int) bool {
    if !bytes.HasPrefix(hdr, []byte("bytes=-")) { return true }
    return contentLength > 0
}

start, end, err := fs.ParseByteRange(hdr, cl)
if err != nil && strings.Contains(err.Error(), "invalid for empty content") {
    start, end = 0, -1 // serve empty body
}

When it happens

Trigger: Requesting Range: bytes=-100 (or any '-N') against a zero-length file or a handler whose contentLength is 0 or negative; direct ParseByteRange(bytes=-N, 0) calls.

Common situations: Download resumers hitting a file truncated to 0 bytes (upload in progress, emptied log); serving empty placeholder files; caching layers that lost the real content length.

Related errors

• unsupported range units: %q: expecting %q
• missing byte range in %q
• missing the end position of byte range in %q
• the start position of byte range cannot exceed %d. byte rang
• the start position of byte range cannot exceed the end posit

AI-assisted analysis of valyala/fasthttp@c96f600972 (2026-08-31). Data as JSON: /api/errors/cf4c708fa1bb05f1. Report an issue: GitHub.