AlistGo/alist · warning · ErrInvalid

invalid range

Error message

invalid range

What it means

ErrInvalid from pkg/http_range.ParseRange: the Range header string is syntactically invalid — it is either missing the required `bytes=` prefix, or a subsequent byte-range-spec inside a comma-separated list fails to parse.

Source

Thrown at pkg/http_range/range.go:30

// Range specifies the byte range to be sent to the client.
type Range struct {
	Start  int64
	Length int64 // limit of bytes to read, -1 for unlimited
}

// ContentRange returns Content-Range header value.
func (r Range) ContentRange(size int64) string {
	return fmt.Sprintf("bytes %d-%d/%d", r.Start, r.Start+r.Length-1, size)
}

var (
	// ErrNoOverlap is returned by ParseRange if first-byte-pos of
	// all the byte-range-spec values is greater than the content size.
	ErrNoOverlap = errors.New("invalid range: failed to overlap")

	// ErrInvalid is returned by ParseRange on invalid input.
	ErrInvalid = errors.New("invalid range")
)

// ParseRange parses a Range header string as per RFC 7233.
// ErrNoOverlap is returned if none of the ranges overlap.
// ErrInvalid is returned if s is invalid range.
func ParseRange(s string, size int64) ([]Range, error) { // nolint:gocognit
	if s == "" {
		return nil, nil // header not present
	}
	const b = "bytes="
	if !strings.HasPrefix(s, b) {
		return nil, ErrInvalid
	}
	var ranges []Range
	noOverlap := false
	for _, ra := range strings.Split(s[len(b):], ",") {
		ra = textproto.TrimString(ra)
		if ra == "" {

View on GitHub (pinned to 843d9dc814)

Solutions

1. Send the header with the bytes unit prefix: `Range: bytes=0-1023`
2. Ensure each comma-separated spec matches `first-last`, `first-`, or `-suffix` with decimal digits
3. Validate/normalize the header at your trust boundary before passing it to ParseRange

Example fix

// before
r.Header.Set("Range", "0-1023") // missing bytes= unit

// after
r.Header.Set("Range", "bytes=0-1023")

func validRangeHeader(s string) bool {
	return strings.HasPrefix(s, "bytes=")
}
if !validRangeHeader(hdr) { hdr = "" /* ignore header */ }

if _, err := http_range.ParseRange(hdr, size); errors.Is(err, http_range.ErrInvalid) {
	// ignore malformed Range and serve the full entity (RFC-sanctioned behavior)
	hdr = ""
}

When it happens

Trigger: Calling http_range.ParseRange("500-1000", size) (no bytes= unit), or a malformed spec like `bytes=a-b` or an empty spec after a comma causes ParseRange of remaining specs to return ErrInvalid.

Common situations: Custom clients building Range headers by hand without the `bytes=` prefix, proxies stripping or rewriting the header, or passing an OpenRange-style string unsupported by this parser.

Related errors

• invalid range: failed to overlap
• can't create RangeReadCloser since URL is empty in link
• invalid label ID '%s': %v
• invalid label_id '%s': %v
• missing cookie or qrcode account

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